Introduction to the Virtual Machine console service
The Virtual Machine (VM) console service provides managed access to a VM hosted in an Operator Nexus Instance. It uses Azure Private Link Service (PLS) to provide network connectivity on Azure private network. The VM Console service is a secure and private way to access a VM without exposing it to the public internet.
For more information about networking resources that enables private connectivity to an Operator Nexus Instance, see Introduction to Azure Private Link.
This document provides guided instructions of how to use the VM Console service to establish a session with a Virtual Machine in an Operator Nexus Instance.
This guide helps you to:
- Establish a secure private network connectivity between your network and the Cluster Manager's private network.
- Create a Console resource in your workload/tenant resource group using the
az networkcloud virtualmachine console
CLI command. - Start an SSH session to connect to the Virtual Machine's Console.
Note
In order to avoid passing the --subscription
parameter to each Azure CLI command, execute the following command:
az account set --subscription "your-subscription-ID"
Before you begin
- Install the latest version of the appropriate CLI extensions.
Setting variables
To help set up the environment for access to Virtual Machines, define these environment variables used by the various commands throughout this guide.
Note
These environment variable values do not reflect a real deployment and users MUST change them to match their environments.
It should be noted that the first set of variables in the section below are for the Cluster Manager not the Cluster.
The CM_EXTENDED_LOCATION value can be found with the command az networkcloud virtualmachine show --name <virtual machine name> --resource-group <virtual machine's resource group> --query "consoleExtendedLocation" | jq -r '.consoleExtendedLocation.name'
.
# CM_HOSTED_RESOURCES_RESOURCE_GROUP: Cluster Manager resource group name
export CM_HOSTED_RESOURCES_RESOURCE_GROUP="my-contoso-console-rg"
# VIRTUAL_MACHINE_NAME: Virtual Machine name you want to access through VM Console service
export VIRTUAL_MACHINE_NAME="my-undercloud-vm"
# CM_EXTENDED_LOCATION: Cluster Manager Extended Location, can be retrieved but you will need access rights to execute certain Azure CLI commands
export CM_EXTENDED_LOCATION=$(az networkcloud virtualmachine show --name ${VIRTUAL_MACHINE_NAME} --resource-group ${VIRTUAL_MACHINE_RG} --query "consoleExtendedLocation" | jq -r '.consoleExtendedLocation.name')
# CONSOLE_PUBLIC_KEY: Public Key matching Private Key to be used when establish `ssh` session, e.g., `ssh -i $HOME/.ssh/id-rsa`
export CONSOLE_PUBLIC_KEY="xxxx-xxxx-xxxxxx-xxxx"
# CONSOLE_EXPIRATION_TIME: Expiration date and time (RFC3339 format) for any `ssh` session with a virtual machine.
export CONSOLE_EXPIRATION_TIME="2023-06-01T01:27:03.008Z"
# PRIVATE_ENDPOINT_RG: Resource group name that Private Endpoint will be created on
export PRIVATE_ENDPOINT_RG="my-work-env-rg"
# PRIVATE_ENDPOINT_NAME: Private Endpoint's name you choose
export PRIVATE_ENDPOINT_NAME="my-work-env-ple"
# PRIVATE_ENDPOINT_CONNECTION_NAME: PLE/PLS connection name you choose
export PRIVATE_ENDPOINT_CONNECTION_NAME="my-contoso-ple-pls-connection"
# PRIVATE_ENDPOINT_REGION: Location where Private Endpoint will be created
export PRIVATE_ENDPOINT_REGION="eastus"
# PRIVATE_ENDPOINT_VNET: Virtual Network to be used by the Private Endpoint
export PRIVATE_ENDPOINT_VNET="my-work-env-ple-vnet"
# PRIVATE_ENDPOINT_SUBNET: Subnetwork to be used by the Private Endpoint
export PRIVATE_ENDPOINT_SUBNET="my-work-env-ple-subnet"
Creating Console Resource
The Console resource provides the information about the Nexus VM. It provides the VM name, public SSH key, expiration date for the SSH session, and so on.
This section provides step-by-step guide to help you to create a Console resource using Azure CLI commands.
To create a Console resource in the Cluster Manager, you'll need to collect some information, for example, resource group (CM_HOSTED_RESOURCES_RESOURCE_GROUP) and custom location (CM_EXTENDED_LOCATION). You have to provide the resource group but you can retrieve the custom location if you have access rights to excute the following commands:
export cluster_manager_resource_id=$(az resource list -g ${CM_HOSTED_RESOURCES_RESOURCE_GROUP} --query "[?type=='Microsoft.NetworkCloud/clusterManagers'].id" --output tsv) export CM_EXTENDED_LOCATION=$(az resource show --ids $cluster_manager_resource_id --query "properties.managerExtendedLocation.name" | tr -d '"')
The first thing before you can establish an SSH session with a VM is to create a Console resource in the Cluster Manager.
az networkcloud virtualmachine console create \ --virtual-machine-name "${VIRTUAL_MACHINE_NAME}" \ --resource-group "${CM_HOSTED_RESOURCES_RESOURCE_GROUP}" \ --extended-location name="${CM_EXTENDED_LOCATION}" type="CustomLocation" \ --enabled True \ --key-data "${CONSOLE_PUBLIC_KEY}" \ [--expiration "${CONSOLE_EXPIRATION_TIME}"]
If you omit the
--expiration
parameter, the expiration will be defaulted to one day after the creation of the Console resource. Also note that theexpiration
date & time format must follow RFC3339 (e.g., 2024-10-04T14:48:00Z) otherwise the creation of the Console resource fails.Note
For a complete synopsis for this command, invoke
az networkcloud console create --help
.Upon successful creation of the Console resource, retrieve the Private Link Service identifier that is required to create Private Link Endpoint (PLE)
export pls_resourceid=$(az networkcloud virtualmachine console show \ --virtual-machine-name "${VIRTUAL_MACHINE_NAME}" \ --resource-group "${CM_HOSTED_RESOURCES_RESOURCE_GROUP}" \ --query "privateLinkServiceId")
Also, retrieve the VM Access ID. You must use this unique identifier as
user
of thessh
session.virtual_machine_access_id=$(az networkcloud virtualmachine console show \ --virtual-machine-name "${VIRTUAL_MACHINE_NAME}" \ --resource-group "${CM_HOSTED_RESOURCES_RESOURCE_GROUP}" \ --query "virtualMachineAccessId")
Note
For a complete synopsis for this command, invoke az networkcloud virtualmachine console show --help
.
Establishing Private Network Connectivity
To establish a secure session with a Virtual Machine, you need to establish private network connectivity between your network and the Cluster Manager's private network.
This private network relies on the Azure Private Link Endpoint (PLE) and the Azure Private Link Service (PLS).
The Cluster Manager automatically creates a PLS so that you can establish a private network connection between your network and the Cluster Manager's private network.
This section provides a step-by-step guide to help you to establish a private network connectivity.
Create the PLE for establishing a private and secure connection between your network and the Cluster Manager's private network. You need the PLS resource ID obtained in Creating Console Resource.
az network private-endpoint create \ --connection-name "${PRIVATE_ENDPOINT_CONNECTION_NAME}" \ --name "${PRIVATE_ENDPOINT_NAME}" \ --private-connection-resource-id "${pls_resourceid}" \ --resource-group "${PRIVATE_ENDPOINT_RG}" \ --vnet-name "${PRIVATE_ENDPOINT_VNET}" \ --subnet "${PRIVATE_ENDPOINT_SUBNET}" \ --manual-request false
Note
You will need only one Private Endpoint per Cluster Manager.
Retrieve the private IP address allocated to the PLE, which you need when establishing the
ssh
session.export ple_interface_id=$(az network private-endpoint list --resource-group ${PRIVATE_ENDPOINT_RG} --query "[0].networkInterfaces[0].id" -o tsv) export sshmux_ple_ip=$(az network nic show --ids $ple_interface_id --query 'ipConfigurations[0].privateIPAddress' -o tsv) echo "sshmux_ple_ip: ${sshmux_ple_ip}"
Establishing an SSH session with Virtual Machine
At this point, you have the virtual_machine_access_id
and the sshmux_ple_ip
. This input is the info needed for establishing a session with the VM.
The VM Console service is a ssh
server that "relays" the session to a Nexus VM. The sshmux_ple_ip
indirectly references the VM Console service and the virtual_machine_access_id
the identifier for the VM.
Important
The VM Console service listens to port 2222
, therefore you must specify this port number in the ssh
command.
SSH [-i path-to-private-SSH-key] -p 2222 $virtual_machine_access_id@$sshmux_ple_ip
The VM Console service was designed to allow only one session per Virtual Machine. Anyone establishing another successful session to a VM closes an existing session.
Important
The private SSH key used for authenticating the session (default: $HOME/.ssh/id_rsa
) MUST match the public SSH key passed as a parameter when creating the Console resource.
Updating Console Resource
You can disable the session to a VM by updating the expiration date/time and the public SSH key used when creating the session with a VM.
az networkcloud virtualmachine console update \
--virtual-machine-name "${VIRTUAL_MACHINE_NAME}" \
--resource-group "${VM_RESOURCE_GROUP}" \
[--enabled True | False] \
[--key-data "${CONSOLE_PUBLIC_KEY}"] \
[--expiration "${CONSOLE_EXPIRATION_TIME}"]
If you want to disable access to a VM, you need to update the Console resource with the parameter enabled False
. This update closes any existing session and restricts any later sessions.
Note
Before creating a session to a VM, the corresponding Console resource must be set to --enabled True
.
When a Console --expiration
time expires, it closes any session corresponding the Console resource. You'll need to update the expiration time with a future value so that you can establish a new session.
When you update the Console's public SSH key, the VM Console service closes all active sessions. You present a new private SSH key to create a new session.
Cleaning Up (Optional)
To clean up your VM Console environment setup, you need to delete the Console resource and your Private Link Endpoint.
Deleting your Console resource
az networkcloud virtualmachine console delete \ --virtual-machine-name "${VIRTUAL_MACHINE_NAME}" \ --resource-group "${VM_RESOURCE_GROUP}"
Deleting the Private Link Endpoint
az network private-endpoint delete \ --name ${PRIVATE_ENDPOINT_NAME}-ple \ --resource-group ${PRIVATE_ENDPOINT_NAME}-rg