Update SSH docs

eksctl-io · Feb 15, 2021 · 1e8f353 · 1e8f353
1 parent 5392c93
commit 1e8f353
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 16 deletions.
diff --git a/examples/07-ssh-keys.yaml b/examples/07-ssh-keys.yaml
@@ -27,14 +27,19 @@ nodeGroups:
     instanceType: m5.large
     desiredCapacity: 1
     ssh: # import inline public key
-        publicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDqZEdzvHnK/GVP8nLngRHu/GDi/3PeES7+Bx6l3koXn/Oi/UmM9/jcW5XGziZ/oe1cPJ777eZV7muEvXg5ZMQBrYxUtYCdvd8Rt6DIoSqDLsIPqbuuNlQoBHq/PU2IjpWnp/wrJQXMk94IIrGjY8QHfCnpuMENCucVaifgAhwyeyuO5KiqUmD8E0RmcsotHKBV9X8H5eqLXd8zMQaPl+Ub7j5PG+9KftQu0F/QhdFvpSLsHaxvBzA5nhIltjkaFcwGQnD1rpCM3+UnQE7Izoa5Yt1xoUWRwnF+L2TKovW7+bYQ1kxsuuiX149jXTCJDVjkYCqi7HkrXYqcC1sbsror someuser@hostname"
+      publicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDqZEdzvHnK/GVP8nLngRHu/GDi/3PeES7+Bx6l3koXn/Oi/UmM9/jcW5XGziZ/oe1cPJ777eZV7muEvXg5ZMQBrYxUtYCdvd8Rt6DIoSqDLsIPqbuuNlQoBHq/PU2IjpWnp/wrJQXMk94IIrGjY8QHfCnpuMENCucVaifgAhwyeyuO5KiqUmD8E0RmcsotHKBV9X8H5eqLXd8zMQaPl+Ub7j5PG+9KftQu0F/QhdFvpSLsHaxvBzA5nhIltjkaFcwGQnD1rpCM3+UnQE7Izoa5Yt1xoUWRwnF+L2TKovW7+bYQ1kxsuuiX149jXTCJDVjkYCqi7HkrXYqcC1sbsror someuser@hostname"
   - name: ng-5
     instanceType: m5.large
     desiredCapacity: 1
     ssh: # use existing EC2 key but don't allow SSH access to nodegroup (security group is not created to allow SSH access).
       publicKeyName: ec2_dev_key
       allow: false
   - name: ng-6
+    instanceType: m5.large
+    desiredCapacity: 1
+    ssh:
+      enableSsm: true
+  - name: ng-7
     instanceType: m5.large
     desiredCapacity: 1
     # no SSH
diff --git a/pkg/apis/eksctl.io/v1alpha5/assets/schema.json b/pkg/apis/eksctl.io/v1alpha5/assets/schema.json
@@ -1612,22 +1612,28 @@
       "properties": {
         "allow": {
           "type": "boolean",
-          "description": "Enables/Disables the security group configuration. Values provided by SourceSecurityGroupIDs are ignored if set to false",
-          "x-intellij-html-description": "Enables/Disables the security group configuration. Values provided by SourceSecurityGroupIDs are ignored if set to false"
+          "description": "If Allow is true the SSH configuration provided is used, otherwise it is ignored. Only one of PublicKeyPath, PublicKey and PublicKeyName can be configured",
+          "x-intellij-html-description": "If Allow is true the SSH configuration provided is used, otherwise it is ignored. Only one of PublicKeyPath, PublicKey and PublicKeyName can be configured"
         },
         "enableSsm": {
           "type": "boolean",
           "description": "Enables the ability to [SSH onto nodes using SSM](/introduction#ssh-access)",
           "x-intellij-html-description": "Enables the ability to <a href=\"/introduction#ssh-access\">SSH onto nodes using SSM</a>"
         },
         "publicKey": {
-          "type": "string"
+          "type": "string",
+          "description": "Public key to be added to the nodes SSH keychain. If Allow is false this value is ignored.",
+          "x-intellij-html-description": "Public key to be added to the nodes SSH keychain. If Allow is false this value is ignored."
         },
         "publicKeyName": {
-          "type": "string"
+          "type": "string",
+          "description": "Public key name in EC2 to be added to the nodes SSH keychain. If Allow is false this value is ignored.",
+          "x-intellij-html-description": "Public key name in EC2 to be added to the nodes SSH keychain. If Allow is false this value is ignored."
         },
         "publicKeyPath": {
-          "type": "string"
+          "type": "string",
+          "description": "The path to the SSH public key to be added to the nodes SSH keychain. If Allow is true this value defaults to \"~/.ssh/id_rsa.pub\", otherwise the value is ignored.",
+          "x-intellij-html-description": "The path to the SSH public key to be added to the nodes SSH keychain. If Allow is true this value defaults to &quot;~/.ssh/id_rsa.pub&quot;, otherwise the value is ignored."
         },
         "sourceSecurityGroupIds": {
           "items": {

diff --git a/pkg/apis/eksctl.io/v1alpha5/schema.go b/pkg/apis/eksctl.io/v1alpha5/schema.go
diff --git a/pkg/apis/eksctl.io/v1alpha5/types.go b/pkg/apis/eksctl.io/v1alpha5/types.go
@@ -1065,14 +1065,16 @@ type (
 
 	// NodeGroupSSH holds all the ssh access configuration to a NodeGroup
 	NodeGroupSSH struct {
-		// +optional Enables/Disables the security group configuration. Values provided by SourceSecurityGroupIDs
-		// are ignored if set to false
+		// +optional If Allow is true the SSH configuration provided is used, otherwise it is ignored. Only one of
+		// PublicKeyPath, PublicKey and PublicKeyName can be configured
 		Allow *bool `json:"allow"`
-		// +optional
+		// +optional The path to the SSH public key to be added to the nodes SSH keychain. If Allow is true this value
+		// defaults to "~/.ssh/id_rsa.pub", otherwise the value is ignored.
 		PublicKeyPath *string `json:"publicKeyPath,omitempty"`
-		// +optional
+		// +optional Public key to be added to the nodes SSH keychain. If Allow is false this value is ignored.
 		PublicKey *string `json:"publicKey,omitempty"`
-		// +optional
+		// +optional Public key name in EC2 to be added to the nodes SSH keychain. If Allow is false this value
+		// is ignored.
 		PublicKeyName *string `json:"publicKeyName,omitempty"`
 		// +optional
 		SourceSecurityGroupIDs []string `json:"sourceSecurityGroupIds,omitempty"`

diff --git a/pkg/ctl/cmdutils/configfile_test.go b/pkg/ctl/cmdutils/configfile_test.go
@@ -266,8 +266,8 @@ var _ = Describe("cmdutils configfile", func() {
 				{"03-two-nodegroups.yaml", 2, false, false},
 				{"05-advanced-nodegroups.yaml", 3, true, false},
 				{"05-advanced-nodegroups.yaml", 3, false, false},
-				{"07-ssh-keys.yaml", 6, true, false},
-				{"07-ssh-keys.yaml", 6, false, false},
+				{"07-ssh-keys.yaml", 7, true, false},
+				{"07-ssh-keys.yaml", 7, false, false},
 				{"15-managed-nodes.yaml", 4, true, true},
 				{"15-managed-nodes.yaml", 4, false, true},
 				{"20-bottlerocket.yaml", 2, false, false},

diff --git a/userdocs/src/usage/managing-nodegroups.md b/userdocs/src/usage/managing-nodegroups.md
@@ -160,6 +160,35 @@ There are no specific commands in `eksctl`to update the labels of a nodegroup bu
 kubectl label nodes -l alpha.eksctl.io/nodegroup-name=ng-1 new-label=foo
 ```
 
+### SSH Access
+You can enable SSH access for nodegroups by configuring one of `publicKey`, `publicKeyName` and `publicKeyPath` in your
+nodegroup configuration. Alternatively you can use [AWS Systems Manager (SSM)](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html#sessions-start-cli) to SSH onto nodes, by configuring the nodegroup with `enableSsm`:
+
+
+```yaml
+nodeGroups:
+  - name: ng-1
+    instanceType: m5.large
+    desiredCapacity: 1
+    ssh: # import public key from file
+      publicKeyPath: ~/.ssh/id_rsa_tests.pub
+  - name: ng-2
+    instanceType: m5.large
+    desiredCapacity: 1
+    ssh: # use existing EC2 key
+      publicKeyName: ec2_dev_key
+  - name: ng-3
+    instanceType: m5.large
+    desiredCapacity: 1
+    ssh: # import inline public key
+      publicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDqZEdzvHnK/GVP8nLngRHu/GDi/3PeES7+Bx6l3koXn/Oi/UmM9/jcW5XGziZ/oe1cPJ777eZV7muEvXg5ZMQBrYxUtYCdvd8Rt6DIoSqDLsIPqbuuNlQoBHq/PU2IjpWnp/wrJQXMk94IIrGjY8QHfCnpuMENCucVaifgAhwyeyuO5KiqUmD8E0RmcsotHKBV9X8H5eqLXd8zMQaPl+Ub7j5PG+9KftQu0F/QhdFvpSLsHaxvBzA5nhIltjkaFcwGQnD1rpCM3+UnQE7Izoa5Yt1xoUWRwnF+L2TKovW7+bYQ1kxsuuiX149jXTCJDVjkYCqi7HkrXYqcC1sbsror someuser@hostname"
+  - name: ng-4
+    instanceType: m5.large
+    desiredCapacity: 1
+    ssh: # enable SSH using SSM
+      enableSsm: true
+```
+
 ### Deleting and draining
 
 To delete a nodegroup, run: