Contact UsTry it for free
© 2025 Direct Cursus Technology L.L.C.

Connecting to a node via OS Login

Written by
Updated at November 27, 2025

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 CLI installed yet, install and initialize it.

    By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command 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:

    • 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. Enable 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. Navigate to the Node group tab.

    4. Select the node group you need.

    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 CLI installed yet, install and initialize it.

    By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command 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 get the node group name with the 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 property to the node group description, or change it if it already exists.

      In this property, 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. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

      2. Run this command:

        terraform validate

        Terraform will show any errors found in your configuration files.

    4. Confirm updating the resources.

      1. Run this command to view the planned changes:

        terraform plan

        If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

        1. Run this command:

          terraform apply

        2. Confirm updating the resources.

        3. Wait for the operation to complete.

      Timeouts

      The Terraform provider sets time limits for operations with Managed Service for Kubernetes cluster node groups:

      • Creating and editing: 60 minutes.
      • Deleting: 20 minutes.

      Operations in excess of this time will be interrupted.

      How do I modify these limits?

      Add the timeouts section to the cluster node group description, e.g.:

      resource "yandex_kubernetes_node_group" "<node_group_name>" {
  ...
  timeouts {
    create = "1h30m"
    update = "1h30m"
    delete = "60m"
  }
}

    For more information, see this Terraform provider guide.

    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, providing the following in your 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 current node group metadata as key=value pairs without any changes.

        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

        • Current metadata keys in a node group:

          "nodeTemplate": {
    "metadata": {
        "enable-oslogin": "undefined",
        "<current_key_1>": "<current_value_1>",
        "<current_key_2>": "<current_value_2>"
    },
    ...
}

        • Metadata keys to provide in an API request:

          "nodeTemplate": {
    "metadata": {
        "enable-oslogin": "true",
        "<current_key_1>": "<current_value_1>",
        "<current_key_2>": "<current_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 connecting 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>

    Note

    For service accounts, OS Login profiles are not created automatically. To connect to a VM or Kubernetes node on behalf of a service account, you need to manually create an OS Login profile.

Connect to the node over SSH

  1. Export the OS Login certificate.

    Note

    The certificate is valid for one hour. Afterwards, 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 <path_to_certificate_file> <user_login>@<node_public_IP_address>

    Where:

    • <path_to_certificate_file>: Path to the certificate's Identity file you saved earlier, e.g., /home/user1/.ssh/yc-cloud-id-b1gia87mbaom********-orgusername.

    • <user_login>: User login as set in their OS Login profile. This login is also specified at the end of the name of the exported OS Login certificate. In the example above, it is orgusername.

      Note

      For service accounts, OS Login profiles are not created automatically. To connect to a VM or Kubernetes node on behalf of a service account, you need to manually create an OS Login profile.

    • <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 into the terminal and press Enter.

Previous
Connecting to a node over SSH
Next
Updating Kubernetes