This document explains how to establish a network connection to a virtual machine
(VM) instance in Google Distributed Cloud (GDC) air-gapped.

Google Distributed Cloud (GDC) air-gapped 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).

This document is for developers in platform administrator or application operator
groups that connect to VM instances in a Distributed Cloud
environment. For more information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

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

- [Enable access management](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/manage-the-os/guest-environment.md.txt). You *cannot* proceed without access management enabled on the guest environment. By default, access management is enabled on new VMs.
- [Enable VM external access](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/connect-to-vm/ip-addresses.md.txt) for any peer on Transmission Control Protocol (TCP) port 22.

- Login access to the cluster. Follow the CLI steps in [Sign in](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/iam/sign-in.md.txt#cli) to sign in to the cluster.
- To use `gdcloud` command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the [`gdcloud` CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-overview.md.txt). All commands for Distributed Cloud use the `gdcloud` or `kubectl` CLI, and require an operating system (OS) environment.

### Get the kubeconfig file path

- To run commands against the Management API server, ensure you have the following resources:
  1. [Sign in and generate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/iam/sign-in.md.txt#cli) the
     kubeconfig file for the Management API server if you don't have one.

  2. Use the path to the kubeconfig file of the Management API server to replace
     `MANAGEMENT_API_SERVER` in these instructions.

### Request IAM roles

- Contact your IAM Project Admin to request the following roles on your project:
  - **Virtual Machine Project Admin** (`project-vm-admin`): create, modify, list,
    and delete VMs in the project namespace.

  - **Project Viewer** (`project-viewer`): view all resources within the project
    namespaces.

- All VM roles must bind to the namespace of the project where the VM resides. Follow the steps to [verify](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/preparation.md.txt#verify-user-access) your access.

## Establish a VM connection

- This section describes how to establish a connection to a VM with a specific operating system (OS).

### Connect to a VM

- To establish a connection to a VM with a specific OS, use the GDC console, gdcloud CLI, or the [Virtual Machine Manager API](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/virtualmachine/vmm-api-overview.md.txt).

### Console

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.

### gdcloud

Connect to a VM using SSH by running the [`gdcloud compute ssh` command](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-reference/gdcloud-compute-ssh.md.txt):

```bash
gdcloud compute ssh VM_NAME \
  --project=PROJECT_ID
```

Replace the following variables:

- <var translate="no">VM_NAME</var>: the name of the VM.
- <var translate="no">PROJECT_ID</var>: the ID of the project that contains the VM.

If you have
[set default properties](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-manage-properties.md.txt#set-properties)
for the CLI, you can omit the `--project` flag from this command. For example:

```bash
gdcloud compute ssh VM_NAME
```

### API

The `VirtualMachine` resource uses a `GuestEnvironmentSynced` condition to
indicate its boot status. When the `GuestEnvironmentSynced` condition is
`True`, this indicates that VM has finished booting and is ready for SSH
connections.

The following sample snippet shows a `VirtualMachine` resource with the
`GuestEnvironmentSynced` condition set to `True`:

    {
        "apiVersion": "virtualmachine.gdc.goog/v1",
        "kind": "VirtualMachine",
        ...
        "status": {
            "conditions": [
                {
                    "lastTransitionTime": "2026-01-25T09:52:52Z",
                    "message": "No message available",
                    "observedGeneration": 3,
                    "reason": "AccessManagementReady",
                    "status": "True",
                    "type": "GuestEnvironmentSynced"
                },
            ],
        },
    }

Once you confirm the `GuestEnvironmentSynced` status for your VM is `True`,
connect to the VM by doing the following:

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

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

Perform 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:

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

   Replace the variables by using the following definitions.

   | Variable | Definition |
   |---|---|
   | `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 `my-ssh-key.pub`. |
   | `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/KEY_FILENAME.pub` path.

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

   ```bash
   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 <var translate="no">`KEY_FILENAME`</var> private key and a TTL
   value of ten minutes:

   ```yaml
   apiVersion: virtualmachine.gdc.goog/v1
   kind: VirtualMachineAccessRequest
   metadata:
     namespace: VM_NAMESPACE
     name: AR_NAME
   spec:
     ssh:
       key: |
         ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAu5kKQCPF... cloudysanfrancisco
       ttl: 10m
     user: USERNAME
     vm: VM_NAME
   ```

   Replace the variables, using the following definitions:

   | Variable | Definition |
   |---|---|
   | `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. |

   > [!IMPORTANT]
   > **Important:** After reaching the TTL value of ten minutes, the VM denies future connections with that key unless you add it again.

3. Create the key:

   ```bash
   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     create -f access_request.yaml
   ```
4. Check the status of your access request:

   ```bash
   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     -n VM_NAMESPACE \
     get virtualmachineaccessrequests.virtualmachine.gdc.goog
   ```

   Replace <var translate="no">`VM_NAMESPACE`</var> with the namespace for the VM.

   A `configured` status indicates that you can connect to the VM.
5. Connect to the VM:

   ```bash
   ssh -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP
   ```

   Replace the following values:
   - <var translate="no">`PATH_TO_PRIVATE_KEY`</var> with the path to the private SSH key file that corresponds to the public key you added to the VM.
   - <var translate="no">`USERNAME`</var> with the username that you specified when you created the SSH key. For example, `cloudysanfrancisco_example_com` or `cloudysanfrancisco`.
   - <var translate="no">`EXTERNAL_IP`</var> with the external [ingress IP address](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/connect-to-vm/ip-addresses.md.txt) of the VM.

### Troubleshooting

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:

   ```bash
   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     -n VM_NAMESPACE \
     get virtualmachines.virtualmachine.gdc.goog VM_NAME
   ```

   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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/connect-to-vm/ip-addresses.md.txt) 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:

   ```bash
   kubectl --kubeconfig MANAGEMENT_API_SERVER \
     -n VM_NAMESPACE \
     describe virtualmachineaccessrequest.virtualmachine.gdc.goog AR_NAME
   ```

   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.