Add EKS Cluster CloudFormation example.

Author: geerlingguy

cluster-aws-eks/README.md

@@ -0,0 +1,55 @@
+# AWS EKS Kubernetes Cluster Example
+
+This example demonstrates the setup of a highly-available AWS EKS Kubernetes cluster using Ansible to manage multiple CloudFormation templates.
+
+## Usage
+
+Prerequisites:
+
+  - You must have an AWS account to run this example.
+  - You must use an IAM account with privileges to create VPCs, Internet Gateways, EKS Clusters, Security Groups, etc.
+  - This IAM account will inherit the `system:master` permissions in the cluster, and only that account will be able to make the initial changes to the cluster via `kubectl` or Ansible.
+  - In your AWS account, you must have an EC2 Key Pair named `eks-example` (or change the name of the `aws_key_name` in `vars/main.yml` to a Key Pair you'd like to use).
+
+### Build the Cluster via CloudFormation Templates with Ansible
+
+Make sure you have the `boto` Python library installed (e.g. via Pip with `pip3 install boto`), and then run the playbook to build the EKS cluster and nodegroup:
+
+    $ ansible-playbook -i inventory main.yml
+
+> Note: EKS Cluster creation is a slow operation, and could take 10-20 minutes.
+
+After the cluster and nodegroup are created, you should see one EKS cluster and three EC2 instances running, and you can start to manage the cluster with Ansible.
+
+### Set up authentication to the cluster via `kubeconfig`
+
+  1. Install the `aws-iam-authenticator` following [these directions](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html).
+  2. Create a `kubeconfig` file for EKS following [these directions](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html):
+
+     ```
+     $ aws eks --region us-east-1 update-kubeconfig --name eks-example --kubeconfig ~/.kube/eks-example
+     ```
+
+     This creates a `kubeconfig` file located in `~/kube/eks-example`.
+  3. Tell `kubectl` where to find the `kubeconfig`:
+
+     ```
+     $ export KUBECONFIG=~/.kube/eks-example
+     ```
+  4. Test that `kubectl` can see the cluster:
+
+     ```
+     $ kubectl get svc
+     NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
+     kubernetes   ClusterIP   10.100.0.1   <none>        443/TCP   19m
+     ```
+
+## Managing the EKS Cluster with Ansible
+
+TODO.
+
+## Delete the cluster and resources
+
+After you're finished testing the cluster, run the `delete.yml` playbook:
+
+    $ ansible-playbook -i inventory delete.yml

cluster-aws-eks/cloudformation/eks-cluster.yml

@@ -0,0 +1,86 @@
+---
+AWSTemplateFormatVersion: '2010-09-09'
+Description: 'EKS Cluster definition.'
+
+Parameters:
+
+  VpcId:
+    Type: String
+    Description: VPC ID.
+
+  Subnets:
+    Type: CommaDelimitedList
+    Description: List of subnets in the VPC.
+
+  ClusterName:
+    Type: String
+    Description: EKS Kubernetes cluster name.
+
+  KubernetesVersion:
+    Type: String
+    Description: EKS Kubernetes cluster version.
+
+Resources:
+
+  ClusterRole:
+    Description: Allows EKS to manage clusters on your behalf.
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: 2012-10-17
+        Statement:
+            Effect: Allow
+            Principal:
+              Service:
+                - eks.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
+        - arn:aws:iam::aws:policy/AmazonEKSServicePolicy
+
+  ClusterControlPlaneSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: Cluster communication with worker nodes.
+      VpcId: !Ref VpcId
+
+  Cluster:
+    Type: "AWS::EKS::Cluster"
+    Properties:
+      Name: !Ref ClusterName
+      Version: !Ref KubernetesVersion
+      RoleArn: !GetAtt ClusterRole.Arn
+      ResourcesVpcConfig:
+        SecurityGroupIds:
+          - !Ref ClusterControlPlaneSecurityGroup
+        SubnetIds: !Ref Subnets
+
+Outputs:
+
+  ClusterName:
+    Value: !Ref ClusterName
+    Description: Cluster Name
+    Export:
+      Name:
+        Fn::Sub: "${AWS::StackName}-ClusterName"
+
+  ClusterArn:
+    Value: !GetAtt Cluster.Arn
+    Description: Cluster Arn
+    Export:
+      Name:
+        Fn::Sub: "${AWS::StackName}-ClusterArn"
+
+  ClusterEndpoint:
+    Value: !GetAtt Cluster.Endpoint
+    Description: Cluster Endpoint
+    Export:
+      Name:
+        Fn::Sub: "${AWS::StackName}-ClusterEndpoint"
+
+  ClusterControlPlaneSecurityGroup:
+    Value: !Ref ClusterControlPlaneSecurityGroup
+    Description: ClusterControlPlaneSecurityGroup
+    Export:
+      Name:
+        Fn::Sub: "${AWS::StackName}-ClusterControlPlaneSecurityGroup"

cluster-aws-eks/cloudformation/eks-nodegroup.yml

@@ -0,0 +1,64 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: 'EKS Nodegroup definition.'
+
+Parameters:
+
+  ClusterName:
+    Type: String
+    Description: The EKS cluster name.
+
+  NodeGroupName:
+    Type: String
+    Description: Unique identifier for the Node Group.
+
+  NodeInstanceType:
+    Type: String
+    Default: t3.medium
+    Description: EC2 instance type for the node instances.
+
+  NodeGroupDesiredCapacity:
+    Type: Number
+    Default: 3
+    Description: Desired capacity of Node Group ASG.
+
+  Subnets:
+    Type: "List<AWS::EC2::Subnet::Id>"
+    Description: The subnets where workers can be created.
+
+  VpcId:
+    Type: "AWS::EC2::VPC::Id"
+    Description: The VPC of the worker instances.
+
+Resources:
+
+  NodeInstanceRole:
+    Type: "AWS::IAM::Role"
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service:
+                - ec2.amazonaws.com
+            Action:
+              - "sts:AssumeRole"
+      ManagedPolicyArns:
+        - "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy"
+        - "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
+        - "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
+      Path: /
+
+  NodeGroup:
+    Type: 'AWS::EKS::Nodegroup'
+    Properties:
+      NodegroupName: !Ref NodeGroupName
+      ClusterName: !Ref ClusterName
+      NodeRole: !GetAtt NodeInstanceRole.Arn
+      InstanceTypes:
+        - !Ref NodeInstanceType
+      ScalingConfig:
+        MinSize: 2
+        DesiredSize: !Ref NodeGroupDesiredCapacity
+        MaxSize: 5
+      Subnets: !Ref Subnets

cluster-aws-eks/cloudformation/vpc.yml

@@ -0,0 +1,173 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: Configure networking and a VPC for an EKS cluster.
+
+Parameters:
+
+  Region:
+    Type: String
+    Default: us-east-1
+    Description: AWS Region for the VPC.
+
+Resources:
+
+  Subnet1a:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref VPC
+      AvailabilityZone:
+        Fn::Sub: '${Region}a'
+      CidrBlock: 172.16.0.0/18
+      Tags:
+      - Key: Name
+        Value: eks-example-a
+
+  Subnet1aRouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      SubnetId: !Ref Subnet1a
+      RouteTableId: !Ref RouteTable
+
+  Subnet1aNetworkAclAssociation:
+    Type: AWS::EC2::SubnetNetworkAclAssociation
+    Properties:
+      SubnetId: !Ref Subnet1a
+      NetworkAclId: !Ref NetworkAcl
+    DependsOn: NetworkAcl
+
+  Subnet1b:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref VPC
+      AvailabilityZone:
+        Fn::Sub: '${Region}b'
+      CidrBlock: 172.16.64.0/18
+      Tags:
+      - Key: Name
+        Value: eks-example-b
+
+  Subnet1bRouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      SubnetId: !Ref Subnet1b
+      RouteTableId: !Ref RouteTable
+
+  Subnet1bNetworkAclAssociation:
+    Type: AWS::EC2::SubnetNetworkAclAssociation
+    Properties:
+      SubnetId: !Ref Subnet1b
+      NetworkAclId: !Ref NetworkAcl
+    DependsOn: NetworkAcl
+
+  Subnet1c:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref VPC
+      AvailabilityZone:
+        Fn::Sub: '${Region}c'
+      CidrBlock: 172.16.128.0/18
+      Tags:
+      - Key: Name
+        Value: eks-example-c
+
+  Subnet1cRouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      SubnetId: !Ref Subnet1c
+      RouteTableId: !Ref RouteTable
+
+  Subnet1cNetworkAclAssociation:
+    Type: AWS::EC2::SubnetNetworkAclAssociation
+    Properties:
+      SubnetId: !Ref Subnet1c
+      NetworkAclId: !Ref NetworkAcl
+    DependsOn: NetworkAcl
+
+  VPC:
+    Type: AWS::EC2::VPC
+    Properties:
+      CidrBlock: 172.16.0.0/16
+      EnableDnsSupport: 'true'
+      EnableDnsHostnames: 'true'
+      Tags:
+      - Key: Name
+        Value: eks-example
+
+  InternetGateway:
+    Type: AWS::EC2::InternetGateway
+    Properties:
+      Tags:
+      - Key: Name
+        Value: eks-example
+
+  AttachGateway:
+    Type: AWS::EC2::VPCGatewayAttachment
+    Properties:
+      VpcId: !Ref VPC
+      InternetGatewayId: !Ref InternetGateway
+
+  RouteTable:
+    Type: AWS::EC2::RouteTable
+    Properties:
+      VpcId: !Ref VPC
+      Tags:
+      - Key: Name
+        Value: eks-example
+
+  Route:
+    Type: AWS::EC2::Route
+    Properties:
+      RouteTableId: !Ref RouteTable
+      DestinationCidrBlock: 0.0.0.0/0
+      GatewayId: !Ref InternetGateway
+    DependsOn: AttachGateway
+
+  NetworkAcl:
+    Type: AWS::EC2::NetworkAcl
+    Properties:
+      VpcId: !Ref VPC
+      Tags:
+      - Key: Name
+        Value: eks-example
+
+  InboundNetworkAclEntrySSH:
+    Type: AWS::EC2::NetworkAclEntry
+    Properties:
+      NetworkAclId: !Ref NetworkAcl
+      RuleNumber: '100'
+      RuleAction: allow
+      Protocol: '-1'
+      Egress: 'false'
+      CidrBlock: 0.0.0.0/0
+      PortRange:
+        From: '22'
+        To: '22'
+    DependsOn: NetworkAcl
+
+  OutboundNetworkAclEntryAll:
+    Type: AWS::EC2::NetworkAclEntry
+    Properties:
+      NetworkAclId: !Ref NetworkAcl
+      RuleNumber: '101'
+      RuleAction: allow
+      Protocol: '-1'
+      Egress: 'true'
+      CidrBlock: 0.0.0.0/0
+      PortRange:
+        From: '0'
+        To: '65535'
+    DependsOn: NetworkAcl
+
+Outputs:
+
+  VpcId:
+    Description: VPC id
+    Value: !Ref VPC
+
+  AvailabilityZones:
+    Description: List of Availability Zones available in the VPC
+    Value: us-east-1a,us-east-1b,us-east-1c
+
+  Subnets:
+    Description: List of Subnets in the VPC
+    Value:
+      Fn::Sub: '${Subnet1a},${Subnet1b},${Subnet1c}'