Published on 14 November 2018 by

We recently announced the new AWS module. It’s automatically generated from the AWS specifications and offers a number of tasks to interact with the Amazon EKS API, allowing you to create and manage Kubernetes clusters with Puppet:

  • Create: amazon_aws:: eks_aws_create_cluster
  • Delete: amazon_aws:: eks_aws_delete_cluster
  • Describe: amazon_aws:: eks_aws_describe_cluster
  • List: amazon_aws:: eks_aws_list_clusters

In this blog post, we’ll walk through how to create a Kubernetes cluster with Puppet Bolt.

Setting up your Kubernetes cluster

Follow these steps to create a Kubernetes cluster on AWS.

  1. Install the new AWS module by following these steps, and Puppet Bolt by following these steps.

  2. Set up your credentials set up for the module (either ~/.aws/credentials or environment variables).

  3. It’s necessary to use a region that allows Kubernetes creation (for now, the available regions for EKS are: us-east-1, us-west-2, eu-west-1). Run the following command to do this: export AWS_REGION=us-east-1.

  4. Grab the role for your EKS cluster set in IAM using Puppet Bolt, by executing the following command: bolt task run --nodes localhost amazon_aws::iam_aws_list_roles. The result will return an array of roles, which include role name, role ID etc. Take a copy of the arn field for your chosen role. The role must have EKS permissions (arn:aws:iam::aws:policy/AmazonEKSClusterPolicy).

  5. Next, set up your Virtual Private Cloud (VPC). Run this command to create a VPC: bolt task run --nodes localhost amazon_aws::ec2_aws_create_vpc cidr_block="your_cidr_block", where your_cidr_block is an IP range, for example 10.1.0.0/16. This will return the created VPC. The status will be pending initially. Take a copy of the vpc_id field.

  6. Before moving on, check if your VPC has been created - run this command: bolt task run --nodes localhost amazon_aws::ec2_aws_describe_vpcs. This should return a state of available for the VPC.

  7. Next, create your subnets. For a Kubernetes cluster you will need at least two (2) subnets, so follow the steps below.

  • Run the command: bolt task run --nodes localhost amazon_aws::ec2_aws_create_subnet vpc_id="your_vpc_id" cidr_block="your_first_subnet_cidr_block", where your_vpc_id is the value of vpc_id taken from step 5 above and the cidr_block is within the VPC range, for example: 10.1.1.0/24. When executed, this command will return the newly created subnet with a state of pending.

  • Now do this again for the next subnet, using a new cidr block, for example 10.1.2.0/24, and create it in a different availability_zone, e.g. us-east-1b. Run the command bolt task run --nodes localhost amazon_aws::ec2_aws_create_subnet vpc_id="your_vpc_id" cidr_block="your_second_subnet_cidr_block" availability_zone="us-east-1b” where your_vpc_id is the value of vpc_id taken from step 5 above and the cidr_block is within the VPC range but a new cidr_block, for example: 10.1.2.0/24. When executed, this command will return the newly created subnet with a state of pending.

  • Before moving on, check if your subnets have been created and grab the subnet IDs by running the following command: bolt task run --nodes localhost amazon_aws::ec2_aws_describe_subnets. This should return a state of available. Take a copy of the values in the field subnet_id.

  1. OK, now the cluster can be created! The following command will create the cluster: bolt task run --nodes localhost amazon_aws::eks_aws_create_cluster name='cluster_name' role_arn='your_role_arn' resources_vpc_config="{:subnet_ids=>[subnet1_id,subnet2_id]}" where cluster_name can be anything you specify, role_arn is the value from field arn step 4 above, and the values for subnet_id are from step 7 above. This will return the details of the cluster you just created, with status CREATING. It may remain in status CREATING for some time, this is normal.

Verifying the Kubernetes cluster

The module provides a command that will let you see a list of names of the available clusters - this will verify that the step above worked. Run bolt task run --nodes localhost amazon_aws::eks_aws_list_clusters and you should see your newly created cluster listed.

Now, we’ll check that the cluster has been created and get more detailed information about the cluster. As noted above, it takes a little time to create the cluster, so run the following command until the status returned is ACTIVE: bolt task run --nodes localhost amazon_aws::eks_aws_describe_cluster name="cluster_name" where cluster_name is the name you assigned in step 8 above.

Now you can connect to your cluster and use the Kubernetes command-line tool kubectl. This will allow you to inspect cluster resources; create, delete, and update components; look at your new cluster; and bring up example apps. Using the information returned when the cluster has status ACTIVE you can use kubectl to connect to you cluster. Firstly, you will need to add the path of your configuration file to the KUBECONFIG environment variable, by running: export KUBECONFIG=$KUBECONFIG:~/.kube/config

You can use the template below with the data provided by the describe cluster task above to create your kubeconfig:

apiVersion: v1
clusters:
- cluster:
    server: <endpoint-url>
    certificate-authority-data: <base64-encoded-ca-cert>
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: aws
  name: aws
current-context: aws
kind: Config
preferences: {}
users:
- name: aws
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1alpha1
      command: aws-iam-authenticator
      args:
        - "token"
        - "-i"
        - "<cluster-name>"
        # - "-r"
        # - "<role-arn>"
      # env:
        # - name: AWS_PROFILE
        #   value: "<aws-profile>"

Amazon EKS uses the AWS IAM Authenticator for Kubernetes with kubectl for cluster authentication. Please make sure you have it installed before setting up your kubeconfig file.

To test if your configuration was correct run: kubectl get svc.

Deleting the Kubernetes cluster

If you want to delete the cluster simply run this command: bolt task run --nodes localhost amazon_aws::eks_aws_delete_cluster name="cluster_name". This will initially return a status of DELETING until such time as it’s deleted.

Watch our overview of the Puppet AWS Module

We recently presented a walkthrough of this module within ten minutes during the recent Puppetize Live event. Check this out for more information and for more of a visual overview.

Feedback

We’d love to get your feedback on this experience. Please feel free to reach out to daniel dot carabas at Puppet dot com or davin dot hanlon at Puppet dot com with feedback. Alternatively, feel free to reach us on Slack in the #forge-modules or #puppet rooms.

Daniel Carabas is a Senior Software Engineer at Puppet on the Cloud and Container modules team.

Learn more

Share via:
Posted in:
The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.