Connect to VMs that use VM Runtime on GDC

This document is intended for application owners that run Google Distributed Cloud. This document shows you how to connect to virtual machines (VMs) that use VM Runtime on GDC. You can connect to VMs directly using an IP address, or using built-in tools for SSH or console 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 .
The virtctl client tool installed as a plugin for kubectl . If needed, 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:

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

 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:

  apiVersion 
 : 
  
 vm.cluster.gke.io/v1 
 kind 
 : 
  
 VirtualMachine 
 metadata 
 : 
  
 name 
 : 
  
 sample-vm 
 spec 
 : 
  
 compute 
 : 
  
 cpu 
 : 
  
 vcpus 
 : 
  
 2 
  
 memory 
 : 
  
 capacity 
 : 
  
 4Gi 
 ... 
   
 osType 
 : 
  
 Linux 
 ...

If necessary, use kubectl edit to update the VirtualMachine custom resource.

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

 kubectl  
get  
gvm  
 VM_NAME 
  
--kubeconfig  
 KUBECONFIG

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

  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 
 : 
  
 UserConfiguration 
   
 status 
 : 
  
 "True" 
  
 type 
 : 
  
 GuestEnvironmentEnabled 
  
 - 
  
 lastTransitionTime 
 : 
  
 "2022-10-06T21:55:57Z" 
  
 message 
 : 
  
 "" 
  
 observedGeneration 
 : 
  
 1 
  
 reason 
 : 
  
 GuestEnvironmentDataSynced 
   
 status 
 : 
  
 "True" 
  
 type 
 : 
  
 GuestEnvironmentSynced 
  
 ...

Enable passwordless SSH access

To enable passwordless SSH access for your VM:

Create a VirtualMachineAccessRequest manifest file, such as vm-access-request.yaml , in the editor of your choice:
```
  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
Use kubectl apply to create the VirtualMachineAccessRequest from the manifest file. For example, if you named your manifest file vm-access-request.yaml ,
```
 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.

To verify that your access request configuration succeeded, check the status of the VirtualMachineAccessRequest :

 kubectl  
get  
vmar  
 VMAR_NAME 
  
-o  
yaml  
--kubeconfig  
 KUBECONFIG

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

  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.

To disable the guest agent:

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

 kubectl  
virt  
stop  
 VM_NAME 
  
--kubeconfig  
 KUBECONFIG

Edit your VM resource:

 kubectl  
edit  
gvm  
 VM_NAME 
  
--kubeconfig  
 KUBECONFIG

Update the VirtualMachine configuration to add an empty spec.guestEnvironment explicitly:

  apiVersion 
 : 
  
 vm.cluster.gke.io/v1alpha1 
 kind 
 : 
  
 VirtualMachine 
 metadata 
 : 
  
 name 
 : 
  
 vm-example 
  
 namespace 
 : 
  
 default 
 spec 
 : 
  
 compute 
 : 
  
 ... 
  
 osType 
 : 
  
 Linux 
   
 guestEnvironment 
 : 
  
 {}

Save and close the updated VM manifest in your editor.

Use kubectl to start the VM:

 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

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

 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

Connect to your VM using an SSH client:
```
 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) and Remote Desktop Protocol (RDP) 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 when you create a VM.

Get the details of your VM to view its IP address:
```
 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 
```
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 .

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

Copy and paste the following YAML manifest:

  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.

Save and close the Service manifest in your editor.

Create the Service using kubectl :

 kubectl  
apply  
-f  
my-service-load-balancer.yaml  
--kubeconfig  
 KUBECONFIG

Get the EXTERNAL-IP address of the load balancer service:

 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

Connect to the EXTERNAL-IP address of the load balancer with a standard protocol, such as using an SSH client:
```
 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 .

To use SSH to connect a Linux VM from the console with the virtctl add-on:
```
 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.
After you have successfully connected using SSH the VM and no longer need the connection, exit the SSH session:
```
  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.

To access a Linux VM from the console, use the virtctl add-on:
```
 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 when you create a VM.
After you've successfully connected to the console of the VM and no longer need the connection, exit the VM session and console:
```
 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 when you create a VM.

To access a VM using VNC, use the virtctl add-on:
```
 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.
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:
```
 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.

Windows guest OS

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

Enable the guest agent in your Windows VM:
1. Configure the VM to enable the guest agent .
2. Use 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.
On your admin workstation, use the following command to reset (or set if you use a new username) the Windows VM password:
```
 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 
 
```