feat(eks): default capacity

packages/@aws-cdk/aws-eks/README.md

@@ -17,20 +17,18 @@
 
 This construct library allows you to define [Amazon Elastic Container Service
 for Kubernetes (EKS)](https://aws.amazon.com/eks/) clusters programmatically.
-
 This library also supports programmatically defining Kubernetes resource
 manifests within EKS clusters.
 
-This example defines an Amazon EKS cluster with a single pod:
+This example defines an Amazon EKS cluster with the following configuration:
+
+- 2x **m5.large** instances (this instance type suits most common use-cases, and is good value for money)
+- Dedicated VPC with default configuration (see [ec2.Vpc](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-ec2-readme.html#vpc))
+- A Kubernetes pod with a container based on the [paulbouwer/hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes) image.
 
 ```ts
 const cluster = new eks.Cluster(this, 'hello-eks');
 
-cluster.addCapacity('default', {
-  instanceType: new ec2.InstanceType('t2.medium'),
-  desiredCapacity: 10,
-});
-
 cluster.addResource('mypod', {
   apiVersion: 'v1',
   kind: 'Pod',
@@ -54,6 +52,51 @@ in the AWS CDK Developer Guide for more details.
 
 Here is a [complete sample](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-eks/test/integ.eks-kubectl.lit.ts).
 
+### Capacity
+
+By default, `eks.Cluster` is created with x2 `m5.large` instances.
+
+```ts
+new eks.Cluster(this, 'cluster-two-m5-large');
+```
+
+The quantity and instance type for the default capacity can be specified through
+the `defaultCapacity` and `defaultCapacityInstance` props:
+
+```ts
+new eks.Cluster(this, 'cluster', {
+  defaultCapacity: 10,
+  defaultCapacityInstance: new ec2.InstanceType('m2.xlarge')
+});
+```
+To disable the default capacity, simply set `defaultCapacity` to `0`:
+
+
+```ts
+new eks.Cluster(this, 'cluster-with-no-capacity', { defaultCapacity: 0 });
+```
+
+The `cluster.defaultCapacity` property will reference the `AutoScalingGroup`
+resource for the default capacity. It will be `undefined` if `defaultCapacity`
+is set to `0`:
+
+```ts
+const cluster = new eks.Cluster(this, 'my-cluster');
+cluster.defaultCapacity!.scaleOnCpuUtilization('up', {
+  targetUtilizationPercent: 80
+});
+```
+
+You can add customized capacity through `cluster.addCapacity()`:
+
+```ts
+cluster.addCapacity('frontend-nodes', {
+  instanceType: new ec2.InstanceType('t2.medium'),
+  desiredCapacity: 3,
+  vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC }
+});
+```
+
 ### Interacting with Your Cluster
 
 The Amazon EKS construct library allows you to specify an IAM role that will be

packages/@aws-cdk/aws-eks/lib/cluster.ts

@@ -13,6 +13,10 @@ import { maxPodsForInstanceType } from './instance-data';
 import { KubernetesResource } from './k8s-resource';
 import { KubectlLayer } from './kubectl-layer';
 
+// defaults are based on https://eksctl.io
+const DEFAULT_CAPACITY_COUNT = 2;
+const DEFAULT_CAPACITY_TYPE = ec2.InstanceType.of(ec2.InstanceClass.M5, ec2.InstanceSize.LARGE);
+
 /**
  * An EKS cluster
  */
@@ -172,6 +176,26 @@ export interface ClusterProps {
    * @default true The cluster can be managed by the AWS CDK application.
    */
   readonly kubectlEnabled?: boolean;
+
+  /**
+   * Number of instances to allocate as an initial capacity for this cluster.
+   * Instance type can be configured through `defaultCapacityInstanceType`,
+   * which defaults to `m5.large`.
+   *
+   * Use `cluster.addCapacity` to add additional customized capacity. Set this
+   * to `0` is you wish to avoid the initial capacity allocation.
+   *
+   * @default 2
+   */
+  readonly defaultCapacity?: number;
+
+  /**
+   * The instance type to use for the default capacity. This will only be taken
+   * into account if `defaultCapacity` is > 0.
+   *
+   * @default m5.large
+   */
+  readonly defaultCapacityInstance?: ec2.InstanceType;
 }
 
 /**
@@ -249,6 +273,12 @@ export class Cluster extends Resource implements ICluster {
    */
   public readonly _k8sResourceHandler?: lambda.Function;
 
+  /**
+   * The auto scaling group that hosts the default capacity for this cluster.
+   * This will be `undefined` if the default capacity is set to 0.
+   */
+  public readonly defaultCapacity?: autoscaling.AutoScalingGroup;
+
   /**
    * The IAM role that was used to create this cluster. This role is
    * automatically added by Amazon EKS to the `system:masters` RBAC group of the
@@ -347,6 +377,13 @@ export class Cluster extends Resource implements ICluster {
 
       this.awsAuth.addMastersRole(props.mastersRole);
     }
+
+    // allocate default capacity if non-zero (or default).
+    const desiredCapacity = props.defaultCapacity === undefined ? DEFAULT_CAPACITY_COUNT : props.defaultCapacity;
+    if (desiredCapacity > 0) {
+      const instanceType = props.defaultCapacityInstance || DEFAULT_CAPACITY_TYPE;
+      this.defaultCapacity = this.addCapacity('DefaultCapacity', { instanceType, desiredCapacity });
+    }
   }
 
   /**