Skip to content

Commit 8e3480c

Browse files
GitHubber17GitHubber17
authored
Merge pull request #83751 from zr-msft/aks-refactor-ssh
[AKS] refactored ssh doc
2 parents 91a0edc + 4e40677 commit 8e3480c

File tree

1 file changed

+78
-94
lines changed

1 file changed

+78
-94
lines changed

‎articles/aks/ssh.md

Lines changed: 78 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -6,149 +6,133 @@ author: mlearned
66

77
ms.service: container-service
88
ms.topic: article
9-
ms.date: 05/24/2019
9+
ms.date: 07/31/2019
1010
ms.author: mlearned
1111

12-
#Customer intent: As a cluster operator, I want to learn how to use SSH to connect to VMs in an AKS cluster to perform maintenance or troubleshoot a problem.
12+
#Customer intent: As a cluster operator, I want to learn how to use SSH to connect to virtual machines in an AKS cluster to perform maintenance or troubleshoot a problem.
1313
---
1414

1515
# Connect with SSH to Azure Kubernetes Service (AKS) cluster nodes for maintenance or troubleshooting
1616

17-
Throughout the lifecycle of your Azure Kubernetes Service (AKS) cluster, you may need to access an AKS node. This access could be for maintenance, log collection, or other troubleshooting operations. You can access AKS nodes using SSH, including Windows Server nodes (currently in preview in AKS). You can also [connect to Windows Server nodes using remote desktop protocol (RDP) connections][aks-windows-rdp]. For security purposes, the AKS nodes are not exposed to the internet.
17+
Throughout the lifecycle of your Azure Kubernetes Service (AKS) cluster, you may need to access an AKS node. This access could be for maintenance, log collection, or other troubleshooting operations. You can access AKS nodes using SSH, including Windows Server nodes (currently in preview in AKS). You can also [connect to Windows Server nodes using remote desktop protocol (RDP) connections][aks-windows-rdp]. For security purposes, the AKS nodes aren't exposed to the internet. To SSH to the AKS nodes, you use the private IP address.
1818

1919
This article shows you how to create an SSH connection with an AKS node using their private IP addresses.
2020

2121
## Before you begin
2222

2323
This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart [using the Azure CLI][aks-quickstart-cli] or [using the Azure portal][aks-quickstart-portal].
2424

25-
You also need the Azure CLI version 2.0.64 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
25+
By default, SSH keys are obtained, or generated, then added to nodes when you create an AKS cluster. This article shows you how to specify different SSH keys than the SSH keys used when you created your AKS cluster. The article also shows you how to determine the private IP address of your node and connect to it using SSH. If you don't need to specify a different SSH key, then you may skip the step for adding the SSH public key to the node.
2626

27-
## Add your public SSH key
27+
This article also assumes you have an SSH key. You can create an SSH key using [macOS or Linux][ssh-nix] or [Windows][ssh-windows]. If you use PuTTY Gen to create the key pair, save the key pair in an OpenSSH format rather than the default PuTTy private key format (.ppk file).
2828

29-
By default, SSH keys are obtained, or generated, then added to nodes when you create an AKS cluster. If you need to specify different SSH keys than those used when you created your AKS cluster, add your public SSH key to the Linux AKS nodes. If needed, you can create an SSH key using [macOS or Linux][ssh-nix] or [Windows][ssh-windows]. If you use PuTTY Gen to create the key pair, save the key pair in an OpenSSH format rather than the default PuTTy private key format (.ppk file).
29+
You also need the Azure CLI version 2.0.64 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
3030

31-
> [!NOTE]
32-
> SSH keys can currently only be added to Linux nodes using the Azure CLI. If you use Windows Server nodes, use the SSH keys provided when you created the AKS cluster and skip to the step on [how to get the AKS node address](#get-the-aks-node-address). Or, [connect to Windows Server nodes using remote desktop protocol (RDP) connections][aks-windows-rdp].
31+
## Configure virtual machine scale set-based AKS clusters for SSH access
3332

34-
The steps to get the private IP address of the AKS nodes is different based on the type of AKS cluster you run:
33+
To configure your virtual machine scale set-based for SSH access, find the name of your cluster's virtual machine scale set and add your SSH public key to that scale set.
3534

36-
* For most AKS clusters, follow the steps to [get the IP address for regular AKS clusters](#add-ssh-keys-to-regular-aks-clusters).
37-
* If you use any preview features in AKS that use virtual machine scale sets, such as multiple node pools or Windows Server container support, [follow the steps for virtual machine scale set-based AKS clusters](#add-ssh-keys-to-virtual-machine-scale-set-based-aks-clusters).
35+
Use the [az aks show][az-aks-show] command to get the resource group name of your AKS cluster, then the [az vmss list][az-vmss-list] command to get the name of your scale set.
3836

39-
### Add SSH keys to regular AKS clusters
37+
```azurecli-interactive
38+
CLUSTER_RESOURCE_GROUP=$(az aks show --resource-group myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv)
39+
SCALE_SET_NAME=$(az vmss list --resource-group $CLUSTER_RESOURCE_GROUP --query [0].name -o tsv)
40+
```
4041

41-
To add your SSH key to a Linux AKS node, complete the following steps:
42+
The above example assigns the name of the cluster resource group for the *myAKSCluster* in *myResourceGroup* to *CLUSTER_RESOURCE_GROUP*. The example then uses *CLUSTER_RESOURCE_GROUP* to list the scale set name and assign it to *SCALE_SET_NAME*.
4243

43-
1. Get the resource group name for your AKS cluster resources using [az aks show][az-aks-show]. The cluster name is assigned to the variable named *CLUSTER_RESOURCE_GROUP*. Replace *myResourceGroup* with the name of your Resource Group where you AKS Cluster is located:
44+
> [!NOTE]
45+
> SSH keys can currently only be added to Linux nodes using the Azure CLI. If you want to connect to a Windows Server node using SSH, use the SSH keys provided when you created the AKS cluster and skip the next set of commands for adding your SSH public key. You will still need the IP address of the node you wish to troubleshoot, which is shown in the final command of this section. Alternatively, you can [connect to Windows Server nodes using remote desktop protocol (RDP) connections][aks-windows-rdp] instead of using SSH.
4446
45-
```azurecli-interactive
46-
CLUSTER_RESOURCE_GROUP=$(az aks show --resource-group myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv)
47-
```
47+
To add your SSH keys to the nodes in a virtual machine scale set, use the [az vmss extension set][az-vmss-extension-set] and [az vmss update-instances][az-vmss-update-instances] commands.
4848

49-
1. List the VMs in the AKS cluster resource group using the [az vm list][az-vm-list] command. These VMs are your AKS nodes:
49+
```azurecli-interactive
50+
az vmss extension set \
51+
--resource-group $CLUSTER_RESOURCE_GROUP \
52+
--vmss-name $SCALE_SET_NAME \
53+
--name VMAccessForLinux \
54+
--publisher Microsoft.OSTCExtensions \
55+
--version 1.4 \
56+
--protected-settings "{\"username\":\"azureuser\", \"ssh_key\":\"$(cat ~/.ssh/id_rsa.pub)\"}"
57+
58+
az vmss update-instances --instance-ids '*' \
59+
--resource-group $CLUSTER_RESOURCE_GROUP \
60+
--name $SCALE_SET_NAME
61+
```
5062

51-
```azurecli-interactive
52-
az vm list --resource-group $CLUSTER_RESOURCE_GROUP -o table
53-
```
63+
The above example uses the *CLUSTER_RESOURCE_GROUP* and *SCALE_SET_NAME* variables from the previous commands. The above example also uses *~/.ssh/id_rsa.pub* as the location for your SSH public key.
5464

55-
The following example output shows the AKS nodes:
65+
> [!NOTE]
66+
> By default, the username for the AKS nodes is *azureuser*.
5667
57-
```
58-
Name ResourceGroup Location
59-
------------------------ --------------------------------------------- ----------
60-
aks-nodepool1-79590246-0 MC_myResourceGroupAKS_myAKSClusterRBAC_eastus eastus
61-
```
68+
After you add your SSH public key to the scale set, you can SSH into a node virtual machine in that scale set using its IP address. View the private IP addresses of the AKS cluster nodes using the [kubectl get command][kubectl-get].
6269

63-
1. To add your SSH keys to the node, use the [az vm user update][az-vm-user-update] command. Provide the resource group name and then one of the AKS nodes obtained in the previous step. By default, the username for the AKS nodes is *azureuser*. Provide the location of your own SSH public key location, such as *~/.ssh/id_rsa.pub*, or paste the contents of your SSH public key:
70+
```console
71+
kubectl get nodes -o wide
72+
```
6473

65-
```azurecli-interactive
66-
az vm user update \
67-
--resource-group $CLUSTER_RESOURCE_GROUP \
68-
--name aks-nodepool1-79590246-0 \
69-
--username azureuser \
70-
--ssh-key-value ~/.ssh/id_rsa.pub
71-
```
74+
The follow example output shows the internal IP addresses of all the nodes in the cluster, including a Windows Server node.
7275

73-
### Add SSH keys to virtual machine scale set-based AKS clusters
76+
```console
77+
$ kubectl get nodes -o wide
7478

75-
To add your SSH key to a Linux AKS node that's part of a virtual machine scale set, complete the following steps:
79+
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
80+
aks-nodepool1-42485177-vmss000000 Ready agent 18h v1.12.7 10.240.0.4 <none> Ubuntu 16.04.6 LTS 4.15.0-1040-azure docker://3.0.4
81+
aksnpwin000000 Ready agent 13h v1.12.7 10.240.0.67 <none> Windows Server Datacenter 10.0.17763.437
82+
```
7683

77-
1. Get the resource group name for your AKS cluster resources using [az aks show][az-aks-show]. The cluster name is assigned to the variable named *CLUSTER_RESOURCE_GROUP*. Replace *myResourceGroup* with the name of your Resource Group where you AKS Cluster is located:
84+
Record the internal IP address of the node you wish to troubleshoot.
7885

79-
```azurecli-interactive
80-
CLUSTER_RESOURCE_GROUP=$(az aks show --resource-group myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv)
81-
```
86+
To access your node using SSH, follow the steps in [Create the SSH connection](#create-the-ssh-connection).
8287

83-
1. Next, get the virtual machine scale set for your AKS cluster using the [az vmss list][az-vmss-list] command. The virtual machine scale set name is assigned to the variable named *SCALE_SET_NAME*:
88+
## Configure virtual machine availability set-based AKS clusters for SSH access
8489

85-
```azurecli-interactive
86-
SCALE_SET_NAME=$(az vmss list --resource-group $CLUSTER_RESOURCE_GROUP --query [0].name -o tsv)
87-
```
90+
To configure your virtual machine availability set-based AKS cluster for SSH access, find the name of your cluster's Linux node, and add your SSH public key to that node.
8891

89-
1. To add your SSH keys to the nodes in a virtual machine scale set, use the [az vmss extension set][az-vmss-extension-set] command. The cluster resource group and virtual machine scale set name are provided from the previous commands. By default, the username for the AKS nodes is *azureuser*. If needed, update the location of your own SSH public key location, such as *~/.ssh/id_rsa.pub*:
92+
Use the [az aks show][az-aks-show] command to get the resource group name of your AKS cluster, then the [az vm list][az-vm-list] command to list the virtual machine name of your cluster's Linux node.
9093

91-
```azurecli-interactive
92-
az vmss extension set \
93-
--resource-group $CLUSTER_RESOURCE_GROUP \
94-
--vmss-name $SCALE_SET_NAME \
95-
--name VMAccessForLinux \
96-
--publisher Microsoft.OSTCExtensions \
97-
--version 1.4 \
98-
--protected-settings "{\"username\":\"azureuser\", \"ssh_key\":\"$(cat ~/.ssh/id_rsa.pub)\"}"
99-
```
94+
```azurecli-interactive
95+
CLUSTER_RESOURCE_GROUP=$(az aks show --resource-group myResourceGroup --name myAKSCluster --query nodeResourceGroup -o tsv)
96+
az vm list --resource-group $CLUSTER_RESOURCE_GROUP -o table
97+
```
10098

101-
1. Apply the SSH key to the nodes using the [az vmss update-instances][az-vmss-update-instances] command:
99+
The above example assigns the name of the cluster resource group for the *myAKSCluster* in *myResourceGroup* to *CLUSTER_RESOURCE_GROUP*. The example then uses *CLUSTER_RESOURCE_GROUP* to list the virtual machine name. The example output shows the name of the virtual machine:
102100

103-
```azurecli-interactive
104-
az vmss update-instances --instance-ids '*' \
105-
--resource-group $CLUSTER_RESOURCE_GROUP \
106-
--name $SCALE_SET_NAME
107-
```
101+
```
102+
Name ResourceGroup Location
103+
------------------------ --------------------------------------------- ----------
104+
aks-nodepool1-79590246-0 MC_myResourceGroupAKS_myAKSClusterRBAC_eastus eastus
105+
```
108106

109-
## Get the AKS node address
107+
To add your SSH keys to the node, use the [az vm user update][az-vm-user-update] command.
110108

111-
The AKS nodes are not publicly exposed to the internet. To SSH to the AKS nodes, you use the private IP address. In the next step, you create a helper pod in your AKS cluster that lets you SSH to this private IP address of the node. The steps to get the private IP address of the AKS nodes is different based on the type of AKS cluster you run:
109+
```azurecli-interactive
110+
az vm user update \
111+
--resource-group $CLUSTER_RESOURCE_GROUP \
112+
--name aks-nodepool1-79590246-0 \
113+
--username azureuser \
114+
--ssh-key-value ~/.ssh/id_rsa.pub
115+
```
112116

113-
* For most AKS clusters, follow the steps to [get the IP address for regular AKS clusters](#ssh-to-regular-aks-clusters).
114-
* If you use any preview features in AKS that use virtual machine scale sets, such as multiple node pools or Windows Server container support, [follow the steps for virtual machine scale set-based AKS clusters](#ssh-to-virtual-machine-scale-set-based-aks-clusters).
117+
The above example uses the *CLUSTER_RESOURCE_GROUP* variable and the node virtual machine name from previous commands. The above example also uses *~/.ssh/id_rsa.pub* as the location for your SSH public key. You could also use the contents of your SSH public key instead of specifying a path.
115118

116-
### SSH to regular AKS clusters
119+
> [!NOTE]
120+
> By default, the username for the AKS nodes is *azureuser*.
117121
118-
View the private IP address of an AKS cluster node using the [az vm list-ip-addresses][az-vm-list-ip-addresses] command. Provide your own AKS cluster resource group name obtained in a previous [az-aks-show][az-aks-show] step:
122+
After you add your SSH public key to the node virtual machine, you can SSH into that virtual machine using its IP address. View the private IP address of an AKS cluster node using the [az vm list-ip-addresses][az-vm-list-ip-addresses] command.
119123

120124
```azurecli-interactive
121125
az vm list-ip-addresses --resource-group $CLUSTER_RESOURCE_GROUP -o table
122126
```
123127

124-
The following example output shows the private IP addresses of the AKS nodes:
128+
The above example uses the *CLUSTER_RESOURCE_GROUP* variable set in the previous commands. The following example output shows the private IP addresses of the AKS nodes:
125129

126130
```
127131
VirtualMachine PrivateIPAddresses
128132
------------------------ --------------------
129133
aks-nodepool1-79590246-0 10.240.0.4
130134
```
131135

132-
### SSH to virtual machine scale set-based AKS clusters
133-
134-
List the internal IP address of the nodes using the [kubectl get command][kubectl-get]:
135-
136-
```console
137-
kubectl get nodes -o wide
138-
```
139-
140-
The follow example output shows the internal IP addresses of all the nodes in the cluster, including a Windows Server node.
141-
142-
```console
143-
$ kubectl get nodes -o wide
144-
145-
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
146-
aks-nodepool1-42485177-vmss000000 Ready agent 18h v1.12.7 10.240.0.4 <none> Ubuntu 16.04.6 LTS 4.15.0-1040-azure docker://3.0.4
147-
aksnpwin000000 Ready agent 13h v1.12.7 10.240.0.67 <none> Windows Server Datacenter 10.0.17763.437
148-
```
149-
150-
Record the internal IP address of the node you wish to troubleshoot. You will use this address in a later step.
151-
152136
## Create the SSH connection
153137

154138
To create an SSH connection to an AKS node, you run a helper pod in your AKS cluster. This helper pod provides you with SSH access into the cluster and then additional SSH node access. To create and use this helper pod, complete the following steps:
@@ -160,17 +144,17 @@ To create an SSH connection to an AKS node, you run a helper pod in your AKS clu
160144
```
161145

162146
> [!TIP]
163-
> If you use Windows Server nodes (currently in preview in AKS), add a node selector to the command to schedule the Debian container on a Linux node as follows:
147+
> If you use Windows Server nodes (currently in preview in AKS), add a node selector to the command to schedule the Debian container on a Linux node:
164148
>
165149
> `kubectl run -it --rm aks-ssh --image=debian --overrides='{"apiVersion":"apps/v1","spec":{"template":{"spec":{"nodeSelector":{"beta.kubernetes.io/os":"linux"}}}}}'`
166150

167-
1. The base Debian image doesn't include SSH components. Once the terminal session is connected to the container, install an SSH client using `apt-get` as follows:
151+
1. Once the terminal session is connected to the container, install an SSH client using `apt-get`:
168152

169153
```console
170154
apt-get update && apt-get install openssh-client -y
171155
```
172156

173-
1. In a new terminal window, not connected to your container, list the pods on your AKS cluster using the [kubectl get pods][kubectl-get] command. The pod created in the previous step starts with the name *aks-ssh*, as shown in the following example:
157+
1. Open a new terminal window, not connected to your container, list the pods on your AKS cluster using the [kubectl get pods][kubectl-get] command. The pod created in the previous step starts with the name *aks-ssh*, as shown in the following example:
174158

175159
```
176160
$ kubectl get pods
@@ -179,21 +163,21 @@ To create an SSH connection to an AKS node, you run a helper pod in your AKS clu
179163
aks-ssh-554b746bcf-kbwvf 1/1 Running 0 1m
180164
```
181165

182-
1. In the first step of this article, you added your public SSH key the AKS node. Now, copy your private SSH key into the pod. This private key is used to create the SSH into the AKS nodes.
166+
1. In an earlier step, you added your public SSH key to the AKS node you wanted to troubleshoot. Now, copy your private SSH key into the helper pod. This private key is used to create the SSH into the AKS node.
183167

184168
Provide your own *aks-ssh* pod name obtained in the previous step. If needed, change *~/.ssh/id_rsa* to location of your private SSH key:
185169

186170
```console
187171
kubectl cp ~/.ssh/id_rsa aks-ssh-554b746bcf-kbwvf:/id_rsa
188172
```
189173

190-
1. Back in the terminal session to your container, update the permissions on the copied `id_rsa` private SSH key so that it is user read-only:
174+
1. Return to the terminal session to your container, update the permissions on the copied `id_rsa` private SSH key so that it is user read-only:
191175

192176
```console
193177
chmod 0600 id_rsa
194178
```
195179

196-
1. Now create an SSH connection to your AKS node. Again, the default username for AKS nodes is *azureuser*. Accept the prompt to continue with the connection as the SSH key is first trusted. You are then provided with the bash prompt of your AKS node:
180+
1. Create an SSH connection to your AKS node. Again, the default username for AKS nodes is *azureuser*. Accept the prompt to continue with the connection as the SSH key is first trusted. You are then provided with the bash prompt of your AKS node:
197181

198182
```console
199183
$ ssh -i id_rsa [email protected]

0 commit comments

Comments
 (0)