Edit

Share via

Configure SSH keys for an AKS Arc cluster

  • Article

Applies to: AKS on Azure Local, version 23H2

Secure Shell Protocol (SSH) is an encrypted connection protocol that provides secure sign-ins over unsecured connections. AKS on Azure Local supports access to a VM in your Kubernetes nodes over SSH using a public-private key pair, also known as SSH keys. For information about how to create and manage SSH keys, see Create and manage SSH keys.

An SSH key is required when deploying an AKS Arc cluster. When you create the cluster, you can either generate a new key pair or use an existing public key. This article explains how to use SSH keys for AKS Arc clusters from Azure CLI and the Azure portal.

Before you begin

To create an AKS Arc cluster, ensure that you have the necessary details from your on-premises infrastructure administrator as described in Create Kubernetes clusters.

Azure CLI

Use the az aksarc create command to create an AKS Arc cluster with an SSH public key. To generate a new key, pass the --generate-ssh-key parameter. To use an existing public key, specify the key or key file using the --ssh-key-value parameter. To restrict SSH access to specific IP addresses, use the --ssh-auth-ips argument. For instructions, see restrict SSH access to virtual machines.

SSH parameter Description
--generate-ssh-key - Required parameter if no preexisting SSH key exists on your local machine. When you specify --generate-ssh-key, Azure CLI automatically generates a set of SSH keys and saves them in the default directory ~/.ssh/.
- If you already have an SSH key on your local machine, the AKS cluster reuses that key. In this scenario, whether you specify --generate-ssh-keys or omit the parameter entirely, it has no effect.
--ssh-key-value - Public key path or key contents for SSH access to node VMs. For example: ssh-rsa AAAAB ... UcyupgH azureuser@linuxvm.
- By default, this key is located in ~/.ssh/id_rsa.pub. You can specify a different location using the --ssh-key-value parameter during cluster creation.
--ssh-auth-ips A comma-separated list of IP addresses or CIDR ranges that are allowed to SSH into the cluster VM.

The following examples show how to use this command:

  • To create an AKS Arc cluster and use the default generated SSH keys:

    az aksarc create -n $<aks_cluster_name> -g $<resource_group_name> --custom-location $<customlocation_ID> --vnet-ids $<logicnet>_Id --aad-admin-group-object-ids <entra-admin-group-object-ids> --generate-ssh-keys

  • To create an AKS Arc cluster using a pre-generated SSH key:

    1. Generate the SSH key. For more information, see Generate and store SSH keys with the Azure CLI:

      az sshkey create --name "mySSHKey" --resource-group $<resource_group_name>

    2. Create an AKS Arc cluster with a pre-generated SSH key:

      az aksarc create -n $<aks_cluster_name> -g $<resource_group_name> --custom-location $<customlocation_ID> --vnet-ids $<logicnet_Id> --aad-admin-group-object-ids <entra-admin-group-object-ids> --ssh-key-value $pubkey.publickey

  • To specify an SSH public key file, include the --ssh-key-value parameter:

    az aksarc create -n $<aks_cluster_name> -g $<resource_group_name> --custom-location $<customlocation_ID> --vnet-ids $<logicnet_Id> --aad-admin-group-object-ids <entra-admin-group-object-ids> --generate-ssh-keys --ssh-key-value ~/.ssh/id_rsa.pub

Azure portal

For information about how to create new SSH keys from the Azure portal, see Create and manage SSH keys in the portal.

When you create an AKS Arc cluster using the Azure portal, provide the necessary information as described in Create a Kubernetes cluster. You can configure your SSH key in the Administrator account section under the Basic tab.

You have three options for SSH key configuration:

  • Generate a new key pair.
  • Use an existing key stored in Azure and select from the stored keys.
  • Use an existing public key by providing the SSH public key value.

Error messages

For information about error messages that can occur when you create and deploy an AKS cluster on Azure Local, see the Control plane configuration validation errors article.

Next steps