> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

VM Runtime on GDC lets you connect to virtual machines (VMs)
directly by using an IP address or through built-in `virtctl` tools for SSH,
serial console, and VNC access. You can also use the guest agent to configure
passwordless SSH access.

## Before you begin

To complete this document, you need access to the following resources:

- A VM that runs in one of your clusters. If needed, [create a VM in Google Distributed Cloud](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/quickstart.md.txt).
- The `virtctl` client tool installed as a plugin for `kubectl`. If needed, [install the virtctl client tool](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/quickstart.md.txt#install_the_virtctl_client_tool).

## Configure passwordless SSH access to VMs

Direct, passwordless SSH access to your VM is facilitated by a guest agent
that's installed by VM Runtime on GDC. Among other duties, the guest
agent installs and expires SSH keys. This capability enables an SSH tunnel for
accessing your VM from clients outside the cluster network.

### Enable the guest agent

To enable the guest agent:

> [!NOTE]
> **Note:** For Windows guest operating systems, there are additional steps required to start the guest agent, initially. For instructions, see the Windows guest OS tab in [Create initial user credentials](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#windows-guest-os).

1. Check your `VirtualMachine` custom resource to confirm it's configured to
   enable the guest agent:

   ```bash
   kubectl get gvm VM_NAME -o yaml --kubeconfig KUBECONFIG
   ```

   The `spec.osType` field should be set to the operating system of your VM,
   `Linux` or `Windows`. The `spec.guestEnvironment` section shouldn't be
   explicitly configured as empty. If the section is configured as empty
   (`guestEnvironment: {}`), you can remove it entirely to enable the guest
   agent.

   Your `VirtualMachine` custom resource for the VM you want to access should
   look like this:

   ```yaml
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachine
   metadata:
     name: sample-vm
   spec:
     compute:
       cpu:
         vcpus: 2
       memory:
         capacity: 4Gi
   ...osType: Linux
   ...
   ```
2. If necessary, use `kubectl edit` to update the `VirtualMachine` custom
   resource.

3. To verify the guest agent is working, check the `status` in your VM custom
   resource:

   ```bash
   kubectl get gvm VM_NAME --kubeconfig KUBECONFIG
   ```

   When the guest agent is working, you see `status: "True"` for the
   `GuestEnvironmentEnabled` and `GuestEnvironmentDataSynced` conditions.

   ```yaml
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachine
   metadata:
     ...
     name: vm-sample-01
     ...
   status:
     conditions:
     - lastTransitionTime: "2022-10-05T22:40:26Z"
       message: ""
       observedGeneration: 1
       reason: UserConfigurationstatus: "True"
   type: GuestEnvironmentEnabled
     - lastTransitionTime: "2022-10-06T21:55:57Z"
       message: ""
       observedGeneration: 1
       reason: GuestEnvironmentDataSyncedstatus: "True"
   type: GuestEnvironmentSynced
     ...
   ```

### Enable passwordless SSH access

To enable passwordless SSH access for your VM:

1. Create a `VirtualMachineAccessRequest` manifest file, such as
   `vm-access-request.yaml`, in the editor of your choice:

   ```yaml
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachineAccessRequest
   metadata:
     name: VMAR_NAME
     namespace: VM_NAMESPACE
   spec:
     vm: VM_NAME
     user: USERNAME
     ssh:
       key: PUBLIC_SSH_KEY
       ttl: EXPIRATION_TIME
   ```

   Replace the following:
   - `VMAR_NAME`: the name of the access request resource.
   - `VM_NAMESPACE`: the namespace for the VM you want to access.
   - `VM_NAME`: the name of the VM you want to access.
   - `USERNAME`: the username for user who is accessing the VM.
   - `PUBLIC_SSH_KEY`: the public key for SSH access. Typically, this is the contents of the `id_rsa.pub` file.
   - `EXPIRATION_TIME`: the `ttl`
     (time-to-live) field specifies the how long the SSH key is valid.

     For example, if you specify `30m` the SSH key expires after 30 minutes.

     This flag uses the following units:
     - `s` for seconds
     - `m` for minutes
     - `h` for hours
     - `d` for days
2. Use `kubectl apply` to create the `VirtualMachineAccessRequest` from the
   manifest file. For example, if you named your manifest file
   `vm-access-request.yaml`,

   ```bash
   kubectl apply -f MANIFEST --kubeconfig KUBECONFIG
   ```

   Replace the following:
   - `MANIFEST`: the name of the access request manifest file. For example, `vm-access-request.yaml`.
   - `KUBECONFIG`: the path to the kubeconfig file of the cluster that hosts the VM you are accessing.
3. To verify that your access request configuration succeeded, check the status
   of the `VirtualMachineAccessRequest`:

   ```bash
   kubectl get vmar VMAR_NAME -o yaml --kubeconfig KUBECONFIG
   ```

   When the configuration is successful, the `status` section includes
   `state: configured`:

   ```yaml
   apiVersion: vm.cluster.gke.io/v1
   kind: VirtualMachineAccessRequest
   metadata:
     ...
     annotations:
       kubectl.kubernetes.io/last-applied-configuration: |
         {"apiVersion":"vm.cluster.gke.io/v1","kind":"VirtualMachineAccessRequest",
         "metadata":{"annotations":{},"name":"vmar-sample","namespace":"default"},
         "spec":{"ssh":{"key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ...jMLHFc=
             sample-user@sample-host","ttl":"5h"},"user":"sample-user","vm":"vm-sample-01"}}
     creationTimestamp: "2022-10-06T21:55:57Z"
     finalizers:
     - vm.cluster.gke.io/vmar-finalizer
     generation: 2
     name: vmar-sample
     namespace: default
     resourceVersion: "13033921"
     uid: 282d72ad-f48d-4e89-af22-336940ac9f58
   spec:
     ssh:
       key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ...jMLHFc= sample-user@sample-host
       ttl: 5m0s
     user: sample-user
     vm: vm-sample-01
   status:
     processedAt: "2022-10-06T21:55:57Z"state: configured
   ```

### Disable the guest agent

When you create a new VM and set the `osType` field, the guest agent is enabled.
While this feature is in Preview, you can disable it by editing the
`VirtualMachine` custom resource. Disabling the guest agent disables passwordless
SSH access to your VM.

> [!NOTE]
> **Note:** Features listed as Preview are covered by the [Pre-GA Offerings Terms](https://cloud.google.com/terms/service-terms#1) of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the [launch stage descriptions](https://cloud.google.com/products#product-launch-stages). Preview offerings are intended for use in test environments only.

To disable the guest agent:

1. Use `kubectl` to stop your VM before you make changes to the configuration:

   ```bash
   kubectl virt stop VM_NAME --kubeconfig KUBECONFIG
   ```

<!-- -->

1. Edit your VM resource:

   ```bash
   kubectl edit gvm VM_NAME --kubeconfig KUBECONFIG
   ```
2. Update the `VirtualMachine` configuration to add an empty `spec.guestEnvironment`
   explicitly:

   ```yaml
   apiVersion: vm.cluster.gke.io/v1alpha1
   kind: VirtualMachine
   metadata:
     name: vm-example
     namespace: default
   spec:
     compute:
     ...
     osType: LinuxguestEnvironment: {}
   ```
3. Save and close the updated VM manifest in your editor.

4. Use `kubectl` to start the VM:

   ```bash
   kubectl virt start VM_NAME --kubeconfig KUBECONFIG
   ```

## Connect using an IP address

If your VM has an accessible IP address and you already have the credentials to
access the VM, you can connect using a protocol such as SSH, VNC, or RDP.

### Connect through IP address

If you can connect directly to your VM's IP address, use one of the following
methods:

### SSH

1. Get the details of your VM to view its IP address:

   ```bash
   kubectl get gvm VM_NAME --namespace VM_NAMESPACE --kubeconfig KUBECONFIG
   ```

   Replace the following values:
   - `VM_NAME`: name for your VM.
   - `VM_NAMESPACE`: the namespace for your VM.

   The following example output shows the VM information and IP address:

   ```bash
   NAME   STATUS    AGE   IP
   vm1    Running   7m    10.200.0.21
   ```
2. Connect to your VM using an SSH client:

   ```bash
   ssh USERNAME@IP_ADDRESS -i PATH_TO_KEY
   ```

   Replace the following values:
   - `USERNAME`: the username for an account on your VM.
   - `IP_ADDRESS`: the IP address of your VM obtained in the previous step.
   - `PATH_TO_KEY`: the path to the private SSH key.

### VNC or RDP

[Virtual Network Computing (VNC)](https://en.wikipedia.org/wiki/Virtual_Network_Computing)
and [Remote Desktop Protocol (RDP)](https://en.wikipedia.org/wiki/Remote_Desktop_Protocol)
let you use the graphical console to access your VM. When you use an IP
address, you must enable VNC or RDP in the guest OS before you can use
either to connect to the VM. For information about enabling and using VNC or
RDP, consult the documentation for your guest OS.

You also need existing credentials to sign in to the VM, such as those you
define to
[create initial user credentials](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#create_initial_user_credentials)
when you create a VM.

1. Get the details of your VM to view its IP address:

   ```bash
   kubectl get gvm VM_NAME --namespace VM_NAMESPACE --kubeconfig KUBECONFIG
   ```

   Replace the following values:
   - `VM_NAME`: name for your VM.
   - `VM_NAMESPACE`: the namespace for your VM.

   The following example output shows the VM information and IP address:

       NAME   STATUS    AGE   IP
       vm1    Running   7m    10.200.0.21

2. Connect to the IP address of your VM obtained in the previous step using a
   client tool and the appropriate port such as VNC port `5900` or RDP port
   `3389`.

### Connect through a Service

If your VM connects to the default `pod-network` and you can't communicate
directly to the IP address of your VM, expose the VM behind a load balancer
`Service`.

1. Create a `Service` manifest, such as `my-service-load-balancer.yaml`, in the
   editor of your choice:

   ```bash
   nano my-service-load-balancer.yaml
   ```
2. Copy and paste the following YAML manifest:

   ```yaml
   apiVersion: v1
   kind: Service
   metadata:
     name: VM_NAME-service
   spec:
     selector:
       kubevirt/vm: VM_NAME
     ports:
     - name: PORT_NAME
       protocol: PROTOCOL_TYPE
       port: EXTERNAL_PORT
       targetPort: TARGET_PORT
     type: LoadBalancer
   ```

   In this `Service` manifest type, replace the following values:
   - `VM_NAME`: the name for your VM to expose for remote access.
   - `PORT_NAME`: the name of your protocol, such as `ssh`, `vnc`, or `rdp`.
   - `PROTOCOL_TYPE`: the protocol type, such as `TCP` for SSH and RDP, or `UDP` for VNC.
   - `EXTERNAL_PORT`: the external port number to expose and that you use to connect to.
   - `TARGET_PORT`: the target port, such as `22` for SSH.
3. Save and close the `Service` manifest in your editor.

4. Create the `Service` using `kubectl`:

   ```bash
   kubectl apply -f my-service-load-balancer.yaml  --kubeconfig KUBECONFIG
   ```
5. Get the `EXTERNAL-IP` address of the load balancer service:

   ```bash
   kubectl get service VM_NAME-service --kubeconfig KUBECONFIG
   ```

   The IP address of the load balancer is displayed, as shown in the following example output:

       NAME          TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
       vm1-service   LoadBalancer   172.26.232.167   10.200.0.51   22:31141/TCP   6d20h

6. Connect to the `EXTERNAL-IP` address of the load balancer with a standard
   protocol, such as using an SSH client:

   ```bash
   ssh USERNAME@LOAD_BALANCER_IP_ADDRESS  -i PATH_TO_KEY
   ```

   Replace the following values:
   - `USERNAME`: the username for an account on your VM.
   - `LOAD_BALANCER_IP_ADDRESS`: the IP address of your load balancer.
   - `PATH_TO_KEY`: the path to the private SSH key.

## Connect directly using SSH

If your client is connected to the same physical network as your bare metal
cluster nodes and you don't require the use of SSH tunnels to connect to the
cluster, you can connect using `kubectl virt ssh`.

1. To use SSH to connect a Linux VM from the console with the `virtctl` add-on:

   ```bash
   kubectl virt ssh USERNAME@VM_NAME --namespace VM_NAMESPACE --kubeconfig KUBECONFIG
   ```

   Replace the following values:
   - `USERNAME`: the username to access your VM. This account is created if it doesn't exist on the VM.
   - `VM_NAME`: the name of your VM.
2. After you have successfully connected using SSH the VM and no longer need the
   connection, exit the SSH session:

   ```bash
   exit
   ```

## Connect directly using the console

If you don't have direct network connectivity to your Linux VM for SSH access,
connect to the console of the VM using the VM Runtime on GDC console.
This method opens a serial console. Upon connection, you are given a command
prompt, instead of a graphical console.

1. To access a Linux VM from the console, use the `virtctl` add-on:

   ```bash
   kubectl virt console VM_NAME --kubeconfig KUBECONFIG
   ```

   Replace `VM_NAME` with the name of your VM.

   When prompted, enter the user credentials for your VM. These credentials must
   exist on the VM, or be applied when the VM is created. If needed see the
   following section to
   [create initial user credentials](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#create_initial_user_credentials)
   when you create a VM.
2. After you've successfully connected to the console of the VM and no longer
   need the connection, exit the VM session and console:

   ```bash
   Ctrl + ]
   ```

## Connect directly using VNC

You can use the `kubectl virt vnc` command to open the Virtual Network Computing
(VNC) graphical console to access your VMs. This method works for VMs running
either a Windows or a Linux guest OS. When you use the `kubectl virt vnc`
command, VM Runtime on GDC opens VNC for you, so you aren't required to
enable VNC in the guest OS.

You need existing credentials to sign in to the VM, such as those you
define to
[create initial user credentials](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#create_initial_user_credentials)
when you create a VM.

1. To access a VM using VNC, use the `virtctl` add-on:

   ```bash
   kubectl virt vnc VM_NAME --kubeconfig KUBECONFIG
   ```

   Replace `VM_NAME` with the name of your VM.

   When prompted, enter the user credentials for your VM.
2. After you've successfully connected to the VNC session of the VM and no
   longer need the connection, log off from the VM to close the VNC connection.

## Create initial user credentials

When you connect to your VM using the console, you must specify user
credentials. The process for creating initial user credentials differs for Linux
and Windows guest operating systems.

### Linux guest OS

For Linux VMs, user credentials can be built in to your custom images, or can
be specified when you create a VM.

- Use the `--configure-initial-password` parameter with `kubectl virt create`
  command:

  ```bash
  kubectl virt create vm VM_NAME \
      --image ubuntu20.04 \
      --os-type Linux \
      --configure-initial-password USERNAME:PASSWORD \
      --kubeconfig KUBECONFIG
  ```

  Replace the following values:
  - `VM_NAME`: name for your VM.
  - `USERNAME`: username for the account to create on the VM.
  - `PASSWORD`: password for the user account.

  This example command creates a Linux VM that runs Ubuntu 20.04. It's
  recommended that you change the initial credentials after you first sign
  in to the VM.

> [!NOTE]
> **Note:** To change credentials on an existing VM, connect to the VM using `kubectl virt console VM_NAME` and then update the credentials within the guest OS.

### Windows guest OS

Use the following steps to reset a password for an existing user or create the
initial password for a new user:

1. Enable the guest agent in your Windows VM:

   1. Configure the VM to [enable the guest agent](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#enable-agent).

   2. Use [VNC or RDP](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/connect-vms.md.txt#vnc-or-rdp) to connect to the VM.

   3. In the VM, navigate to the `guest agent` drive. In most cases, this is
      drive `E:`.

   4. Use PowerShell to run `install.ps1`.

      This installs and starts the guest agent. The guest agent starts
      automatically for subsequent VM reboots.
   5. Close the remote session.

2. On your admin workstation, use the following command to reset (or set if
   you use a new username) the Windows VM password:

   ```bash
   kubectl virt reset-windows-password VM_NAME \
       --user=USERNAME \
       --namespace=VM_NAMESPACE
   ```

   Replace the following:
   - `VM_NAME`: the name of the VM.
   - `USERNAME`: the username you want to reset (or set) the password for. If the username is new, the command creates a new Windows account and sets the initial password.
   - `VM_NAMESPACE`: (Optional) the namespace of the VM. This flag is optional. If not specified, the default namespace, `default`, is used.

   To reset (or set) password without a confirmation prompt, use the optional
   `--force` flag. When you use the `--force` flag, the prompt warns you of
   the consequences of resetting the password for an existing account.
   Without the `--force` flag, the command prompts you to confirm the
   password reset with the following text:

       This command creates an account and sets an initial password for the
       user USERNAME if the account does not already exist.
       If the account already exists, resetting the password can cause the
       LOSS OF ENCRYPTED DATA secured with the current password, including
       files and stored passwords.

       Would you like to set or reset the password for USERNAME (Y/n)?

   After you confirm (or force) the password reset, the command returns the
   new password for the specified VM and username:

       Resetting and retrieving password for USERNAME on VM_NAME

       vm_name:    VM_NAME
       username:   USERNAME
       password:   PASSWORD

## What's next

- [Manage the power state of a VM in Google Distributed Cloud](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/manage-power-state.md.txt).
- [Edit a VM in Google Distributed Cloud](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/edit-vm.md.txt).
- [View VM console logs in Google Distributed Cloud](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/vm-runtime/view-console-logs.md.txt).