Connect to a VM

Google Distributed Cloud Hosted (GDCH) uses key-based SSH authentication to establish connections to virtual machine (VM) instances. By default, passwords aren't configured for local users on VMs with an operating system (OS).

Before you begin

Before connecting to a VM, you must meet the following prerequisites:

  • Enable access management. You cannot proceed without access management enabled on the guest environment. By default, access management is enabled on new VMs.
  • Enable data transfer in on port 22.
  • Login access to the user cluster. Follow the CLI steps in Sign in to log in to the user cluster.
  • If you want to connect to the VM by using the GDCH console, the project that the VM is in needs a ProjectNetworkPolicy custom resource (PNP) that lets data transfer in for any peer on TCP port 22. To diagnose if you don't have a PNP, ask your Infrastructure Operator (IO).

To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the gdcloud CLI. All commands for Distributed Cloud Hosted use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file paths

  1. Run gdcloud auth login to the admin cluster.

    1. Record the path to the generated file, as in this example:

    2. Use the path to replace ORG_ADMIN_KUBECONFIG in these instructions.

Establish an SSH connection in Linux VMs


  1. In the navigation menu, click Virtual Machines > Instances.

  2. In the list of VMs, find the row for the running VM that you want to connect to. In the Connect column, click SSH.

  3. An SSH browser terminal opens. Enter any command in the shell or click FTP to navigate the file structure and upload files.


Connect to a VM using SSH by running the gdcloud compute ssh command

gdcloud compute ssh VM_NAME --project=PROJECT_ID

Replace the following variables:

  • VM_NAME: the name of the VM.
  • PROJECT_ID: the ID of the project that contains the VM.

If you have set default properties for the CLI, you can omit the --project flag from this command. For example:

gdcloud compute ssh VM_NAME


Connect to a VM:

  • Open a terminal.
  • Create an SSH key pair.
  • Upload the public key and username with a time-to-live (TTL) value.

GDCH retrieves the SSH key and username and creates a user account with the username. On VMs, GDCH stores the public key in your user's ~/.ssh/authorized_keys file on the VM.

Complete the following steps to connect to a VM from the command line:

  1. Create an SSH key pair and a username.

    On OS workstations, use the ssh-keygen utility to create a new SSH key pair. The following code sample creates an RSA (Rivest–Shamir–Adleman) key pair:

    ssh-keygen -t rsa -f ~/.ssh/KEY_FILENAME -C USERNAME -b 2048

    Replace the variables by using the following definitions.

    KEY_FILENAME The name for your SSH key file. For example, the my-ssh-key filename generates a private key file named my-ssh-key and a public key file named
    USERNAME Your username on the VM, such as testuser or testuser_gmail_com.

    The ssh-keygen utility saves your private key file in the ~/.ssh/KEY_FILENAME path and your public key file in the ~/.ssh/ path.

    A public key for the user, testuser, is similar to the following example:

    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF... testuser
  2. Upload your key to the VM and create a Kubernetes resource with your public key, username, and time to live (TTL) value for the key.

    The following example uses an access_request.yaml file to grant access to the VM instance with the KEY_FILENAME private key and a TTL value of ten minutes:

    kind: VirtualMachineAccessRequest
      namespace: VM_NAMESPACE
      name: AR_NAME
        key: |
          ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF... cloudysanfrancisco
        ttl: 10m
      user: USERNAME
      vm: VM_NAME

    Replace the variables, using the following definitions.

    VM_NAMESPACE The namespace for the VM.
    AR_NAME The access request name.
    USERNAME Your username on the VM, such as testuser or testuser_gmail_com.
    VM_NAME The name of the VM instance.
  3. Create the key:

    kubectl create -f access_request.yaml --kubeconfig ORG_ADMIN_KUBECONFIG
  4. Check the status of your access request:

    kubectl get -n VM_NAMESPACE --kubeconfig ORG_ADMIN_KUBECONFIG

    Replace VM_NAMESPACE with the namespace for the VM.

    A configured status indicates that you can connect to the VM.

  5. Connect to the VM:


    Replace the following values:

    • PATH_TO_PRIVATE_KEY with the path to the private SSH key file that corresponds to the public key you added to the VM.
    • USERNAME with the username that you specified when you created the SSH key. For example, cloudysanfrancisco_example_com or cloudysanfrancisco.
    • EXTERNAL_IP with the external ingress IP address of the VM.


This section describes how to troubleshoot issues that might occur while connecting to a VM instance after creating the access request.

Work through the following steps to identify possible issues:

  1. Verify that the VM is running. Replace the editable variables with your values in the following command:

    kubectl get VM_NAME -n VM_NAMESPACE --kubeconfig ORG_ADMIN_KUBECONFIG

    If the VM is not running, you cannot connect or configure new requests.

  2. Verify that the VM has been running for a few minutes. If the VM has just started, the required services for SSH access might not be running yet. Typically, they run within five minutes of the boot.

  3. Verify that you didn't exceed the TTL value on the access request. The key is removed after time reaches the TTL value.

  4. If your VirtualMachineAccessRequest shows a configured status, verify the following requirements:

    1. You enabled data transfer in to your VM on port 22.
    2. Your machine routes to the VM. For example, you can use the
      curl -vso /dev/null --connect-timeout 5 EXTERNAL_IP:22 command to check routing.
  5. If your VirtualMachineAccessRequest shows a failed status, view the complete status and review the error message indicating what caused the request to fail:

    kubectl describe AR_NAME -n VM_NAMESPACE --kubeconfig ORG_ADMIN_KUBECONFIG

    Replace the editable variables in the preceding command with your own values.

  6. If the status of your VirtualMachineAccessRequest is blank, the guest environment might not be running.