CircleCI Server v3.x - Creating Your First Cluster (Optional)

If you have never previously set up a Kubernetes cluster, we have provided some tips in this section.

Step 1 - Create

Amazon EKS

CircleCI recommends using eksctl to set up your first cluster on AWS. eksctl will take care of VPC creation, in addition to security group selection.

Before creating the cluster, make sure you have the following:

  1. The latest AWS CLI installed and configured to your AWS account

  2. eksctl installed

  3. kubectl installed

Create a cluster using flags

To create a simple cluster, you can run the command:

eksctl create cluster

Additional flags are available on the command line. See the eksctl introduction for more information.

Create cluster using a configuration file

You can also create a config file for your cluster, for example:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: <your-cluster-name>
  region: <aws-region>

managedNodeGroups:
  - name: <nodegroup-name-1>
    instanceType: <instance-type> # i.e., m5.large. see https://aws.amazon.com/ec2/instance-types/ for available instance types
    minSize: 4 # see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-group.html#cfn-as-group-minsize for more information
    maxSize: 6 # see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-as-group.html#cfn-as-group-maxsize for more information

For more examples on cluster configuration files, see eksctl.io.

When you are finished with your configuration, save it and run:

eksctl create cluster -f <your-cluster-config.yaml>

When using the eksctl tool to create your cluster, you may receive an AWS STS access error: AWS STS access – cannot get role ARN for current session: InvalidClientTokenId.

This may mean your AWS credentials are invalid, or your IAM user does not have permission to create an EKS cluster. Note that the proper IAM permissions are necessary in order to use eksctl. See the AWS documentation regarding prerequisite IAM permissions.

Step 2 - Verify

Once your cluster is finished being created, you should be able to run various kubectl commands to view your cluster resources.

For instance, to view your cluster’s built-in services, you can run:

kubectl cluster-info

Or, to verify that your cluster has worker nodes attached, run:

kubectl get nodes -o wide

For more information on exploring your new cluster, see the following: