Add documentation for launch template and custom AMI support

examples/15-managed-nodes.yaml

@@ -15,6 +15,8 @@ managedNodeGroups:
     maxSize: 4
     availabilityZones: ["us-west-2a", "us-west-2b"]
     volumeSize: 20
+    securityGroups:
+      attachIDs: ["sg-1", "sg-2"]
     ssh:
       allow: true
       publicKeyPath: ~/.ssh/ec2_id_rsa.pub
@@ -32,3 +34,16 @@ managedNodeGroups:
     instanceType: m5.large
     # launch nodegroup in private subnets
     privateNetworking: true
+
+  - name: custom-ami
+    ami: ami-custom
+    preBootstrapCommands:
+      # disable hyperthreading
+      - "for n in $(cat /sys/devices/system/cpu/cpu*/topology/thread_siblings_list | cut -s -d, -f2- | tr ',' '\n' | sort -un); do echo 0 > /sys/devices/system/cpu/cpu${n}/online; done"
+    overrideBootstrapCommand: |
+      /etc/eks/bootstrap.sh custom-ami
+
+  - name: custom-launch-template
+    launchTemplate:
+      id: lt-1234
+      version: "3"

pkg/ctl/cmdutils/configfile_test.go

@@ -21,7 +21,7 @@ var _ = Describe("cmdutils configfile", func() {
 	}
 
 	const examplesDir = "../../../examples/"
-	const numOfExamples = 21
+	const numOfExamples = 22
 
 	Context("load configfiles", func() {
 
@@ -266,8 +266,8 @@ var _ = Describe("cmdutils configfile", func() {
 				{"05-advanced-nodegroups.yaml", 3, false, false},
 				{"07-ssh-keys.yaml", 6, true, false},
 				{"07-ssh-keys.yaml", 6, false, false},
-				{"15-managed-nodes.yaml", 2, true, true},
-				{"15-managed-nodes.yaml", 2, false, true},
+				{"15-managed-nodes.yaml", 4, true, true},
+				{"15-managed-nodes.yaml", 4, false, true},
 				{"20-bottlerocket.yaml", 2, false, false},
 			}
 

userdocs/src/usage/eks-managed-nodes.md

@@ -4,6 +4,7 @@
 
 An EKS managed node group is an autoscaling group and associated EC2 instances that are managed by AWS for an Amazon EKS cluster. Each node group uses the Amazon EKS-optimized Amazon Linux 2 AMI. Amazon EKS makes it easy to apply bug fixes and security patches to nodes, as well as update them to the latest Kubernetes versions. Each node group launches an autoscaling group for your cluster, which can span multiple AWS VPC availability zones and subnets for high-availability.
 
+**NEW** [Launch Template support for managed nodegroups](launch-template-support.md)
 
 !!!info
     The term "unmanaged nodegroups" has been used to refer to nodegroups that eksctl has supported since the beginning and uses by default. The `ClusterConfig` file continues to use the `nodeGroups` field for defining unmanaged nodegroups, and a new field `managedNodeGroups` has been added for defining managed nodegroups.
@@ -107,6 +108,38 @@ managedNodeGroups:
     maxSize: 3
 ```
 
+**NEW** Support for custom AMI, security groups, `instancePrefix`, `instanceName`, `ebsOptimized`, `volumeType`, `volumeName`,
+`volumeEncrypted`, `volumeKmsKeyID`, `volumeIOPS`, `maxPodsPerNode`, `preBootstrapCommands`, `overrideBootstrapCommand`, and `disableIMDSv1`
+
+
+```yaml
+# cluster.yaml
+# A cluster with an unmanaged nodegroup and two managed nodegroups.
+---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+
+metadata:
+  name: managed-cluster
+  region: us-west-2
+
+managedNodeGroups:
+  - name: custom-ng
+    ami: ami-0e124de4755b2734d
+    securityGroups:
+      attachIDs: ["sg-1234"]
+    maxPodsPerNode: 80
+    ssh:
+      allow: true
+    volumeSize: 100
+    volumeName: /dev/xvda
+    volumeEncrypted: true
+    disableIMDSv1: true
+    overrideBootstrapCommand: |
+      /etc/eks/bootstrap.sh managed-cluster --kubelet-extra-args '--node-labels=eks.amazonaws.com/nodegroup=custom-ng,eks.amazonaws.com/nodegroup-image=ami-0e124de4755b2734d'
+```
+
+
 ### Existing clusters
 
 The same switch `--managed` can be used to create a new nodegroup for an
@@ -183,15 +216,13 @@ eksctl scale nodegroup --name=managed-ng-1 --cluster=managed-cluster --nodes=4 -
 EKS Managed Nodegroups are managed by AWS EKS and do not offer the same level of configuration as unmanaged nodegroups.
 The unsupported options are noted below.
 
-- Tags (`managedNodeGroups[*].tags`) in managed nodegroups apply to the EKS Nodegroup resource and do not propagate to
-the provisioned Autoscaling Group like in unmanaged nodegroups.
+- Tags (managedNodeGroups[*].tags) in managed nodegroups apply to the EKS Nodegroup resource and to the EC2 instances launched as part of the nodegroup.
+They do not propagate to the provisioned Autoscaling Group like in unmanaged nodegroups.
 - `iam.instanceProfileARN` is not supported for managed nodegroups.
 - The `amiFamily` field supports only `AmazonLinux2`
 - `instancesDistribution` field is not supported
-- `volumeSize` is the only field supported for configuring volumes
-- Control over the node bootstrapping process and customization of the kubelet are not supported. This includes the
-following fields: `classicLoadBalancerNames`, `maxPodsPerNode`, `taints`, `targetGroupARNs`, `preBootstrapCommands`, `overrideBootstrapCommand`,
-`clusterDNS` and `kubeletExtraConfig`.
+- Full control over the node bootstrapping process and customization of the kubelet are not supported. This includes the
+following fields: `classicLoadBalancerNames`, `taints`, `targetGroupARNs`, `clusterDNS` and `kubeletExtraConfig`.
 - No support for enabling metrics on AutoScalingGroups using `asgMetricsCollection`
 
 ## Note for eksctl versions below 0.12.0

userdocs/src/usage/launch-template-support.md

@@ -0,0 +1,63 @@
+# Launch Template support for Managed Nodegroups
+
+eksctl supports launching managed nodegroups using a provided [EC2 Launch Template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html).
+This enables multiple customization options for nodegroups including providing custom AMIs and security groups, and passing user data for node bootstrapping.
+
+
+## Creating managed nodegroups using a provided launch template
+
+```yaml
+# managed-cluster.yaml
+# A cluster with two managed nodegroups
+---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+
+metadata:
+  name: managed-cluster
+  region: us-west-2
+
+managedNodeGroups:
+  - name: managed-ng-1
+    launchTemplate:
+      id: lt-12345
+      version: "2" # optional (uses the default launch template version if unspecified)
+
+  - name: managed-ng-2
+    minSize: 2
+    desiredCapacity: 2
+    maxSize: 4
+    labels:
+      role: worker
+    tags:
+      nodegroup-name: managed-ng-2
+    privateNetworking: true
+    launchTemplate:
+      id: lt-12345
+
+```
+
+
+## Upgrading a managed nodegroup to use a different launch template version
+
+```shell
+eksctl upgrade nodegroup --name=managed-ng-1 --cluster=managed-cluster --launch-template-version=3
+```
+
+!!!note
+    If a launch template is using a custom AMI, then the new version should also use a custom AMI or the upgrade operation will fail
+
+
+If a launch template is not using a custom AMI, the Kubernetes version to upgrade to can also be specified:
+
+```shell
+eksctl upgrade nodegroup --name=managed-ng-1 --cluster=managed-cluster --launch-template-version=3 --kubernetes-version=1.17
+```
+
+
+## Notes on custom AMI and launch template support
+- When a launch template is provided, the following fields are not supported: instanceType, ami, ssh.allow, ssh.sourceSecurityGroupIds, securityGroups,
+volumeSize, instanceName, instancePrefix, maxPodsPerNode, preBootstrapCommands or overrideBootstrapCommand.
+- When using a custom AMI (`ami`), `overrideBootstrapCommand` must also be set to perform the bootstrapping.
+- `overrideBootstrapCommand` can only be set when using a custom AMI.
+- When a launch template is provided, tags specified in the nodegroup config are not propagated to EC2 instances.