Create Amazon EKS cluster

This section will help you create a Saagie-compatible Kubernetes cluster using the Amazon Elastic Kubernetes Service (EKS).

1. Prerequisites

You need to set up your computer before creating a new cluster.

2. Create or configure cluster

  • Create new cluster

  • Configure existing cluster

  1. Refer to the Amazon EKS User Guide to create your EKS cluster.

    1. Choose the eksctl method.

    2. Confirm that the AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables are defined.

    3. Create a cluster.yml file with the following content:

      apiVersion: eksctl.io/v1alpha5
      kind: ClusterConfig
      
      metadata:
        name: <cluster name> (1)
        region: <region> (2)
        version: "<version>" (3)
      
      nodeGroups:
        - name: ng-1
          instanceType: m5.2xlarge
          desiredCapacity: 3
      1 Replace <cluster name> with the name of your cluster.
      2 Replace <region> with the region in which the cluster will be used.
      3 Replace <version> with a Kubernetes version that is compatible with Saagie. The current compatible version is 1.15. Use quotes around the version number as eksctl requires a string text and not a float number in the YAML file.
  2. Run the command:

    eksctl create cluster -f cluster.yml
  1. If you are using an existing Amazon EKS cluster, create your configuration file by running the following aws command line:

    aws eks --region <aws region> update-kubeconfig --name <cluster name> (1)
    1 Replace <aws region> and <cluster name> with your region and cluster name.
  2. Once your configuration file is created, check the connectivity.

Refer to the Kubernetes documentation if needed.

3. Verify your Kubernetes cluster

  1. Run the following command to verify that you have access to your Kubernetes cluster:

    kubectl get nodes
    • The output should be similar to this:

      NAME                                           STATUS   ROLES    AGE    VERSION
      ip-192-168-15-134.eu-west-1.compute.internal   Ready    <none>   9m8s   v1.13.8-eks-cd3eb0
      ip-192-168-35-150.eu-west-1.compute.internal   Ready    <none>   9m3s   v1.13.8-eks-cd3eb0
      ip-192-168-88-76.eu-west-1.compute.internal    Ready    <none>   9m7s   v1.13.8-eks-cd3eb0
All nodes must have the status ready.

4. Create storage classes

The storage.yml file contains the configuration for your storageClass resources:

  • common-storageclass: Used to store Saagie data, such as databases.

  • <prefix>-storageclass: Used to store job data, such as uploaded artifacts.

  • <prefix>-app-storageclass: Optional storageClass to store app data and job data on different provisioner.

    <prefix> is the same value you determined for your DNS entry.

4.1. Create a storage.yml file

Here is a sample storage.yml for Amazon EKS that can be customized according to your needs:

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: common-storageclass
parameters:
  type: gp2
  fsType: ext4
provisioner: kubernetes.io/aws-ebs
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: <prefix>-storageclass (1)
parameters:
  type: gp2
  fsType: ext4
provisioner: kubernetes.io/aws-ebs

To store app data and job data on different provisioners, include the following in the same storage.yml file:

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: <prefix>-app-storageclass (1)
parameters: (2)

provisioner: (3)
1 Replace <prefix> with the same value determined for your DNS entry.
2 Add the parameters for app data.
3 Indicate your second provisioner used to store app data.

4.2. Apply storage.yml

  1. Run the following command to apply your storage.yml file:

    kubectl apply -f storage.yml
  2. Run the following command to confirm that the storage classes are available:

    kubectl get sc

5. Install Calico

Amazon EKS does not automatically install Calico, which is necessary for your Kubernetes cluster.
  1. If you did not install Calico while creating your cluster, run this command now:

    kubectl apply -f https://raw.githubusercontent.com/aws/amazon-vpc-cni-k8s/master/config/v1.3/calico.yaml (1)
    1 Make sure that the version of Calico is compatible with your cluster.
  2. Refer to Installing Calico on Amazon EKS as needed.

6. Set up a role for Saagie jobs

The Kubernetes pods responsible for running Saagie jobs use a service account associated with an AWS role, which configures access rights.

If you choose to skip it, note that jobs launched on Saagie may obtain admin rights on the AWS API.

  1. First, choose the AWS policy that meets your needs.

    • Example: Jobs won’t need access to AWS resources

      • ARN: arn:aws:iam::aws:policy/AWSDenyAll

    • Example: Jobs need read access to S3

      • ARN: arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

    • Refer to AWS’s user guide to create your own policy.

  2. Then, create the file create-job-role.sh with the following content, defining the variables indicated:

    #!/bin/bash
    set -e
    
    # Define your variables here. Variables are explained below the code block.
    CLUSTER_NAME=<cluster-name> (1)
    SAAGIE_PREFIX=<prefix> (2)
    ROLE_NAME=<role-name> (3)
    AWS_POLICY_ARN=<policy-arn> (4)
    
    ISSUER_URL=$(aws eks describe-cluster \
        --name $CLUSTER_NAME \
        --query cluster.identity.oidc.issuer \
        --output text)
    ISSUER_HOSTPATH=$(echo $ISSUER_URL | cut -f 3- -d'/')
    ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
    PROVIDER_ARN="arn:aws:iam::$ACCOUNT_ID:oidc-provider/$ISSUER_HOSTPATH"
    cat > saagie-job-trust-policy.json << EOF
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "$PROVIDER_ARN"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "${ISSUER_HOSTPATH}:aud": "sts.amazonaws.com"
            },
            "StringLike": {
              "${ISSUER_HOSTPATH}:sub": "system:serviceaccount:${SAAGIE_PREFIX}-project*:*"
            }
          }
        }
      ]
    }
    EOF
    aws iam create-role \
      --role-name $ROLE_NAME \
      --assume-role-policy-document file://saagie-job-trust-policy.json
    aws iam update-assume-role-policy \
      --role-name $ROLE_NAME \
      --policy-document file://saagie-job-trust-policy.json
    aws iam attach-role-policy \
      --role-name $ROLE_NAME \
      --policy-arn $AWS_POLICY_ARN
    aws iam get-role \
      --role-name $ROLE_NAME \
      --query Role.Arn --output text
    1 Replace <cluster-name> with the name of your EKS cluster.
    2 Replace <prefix> with the prefix determined for your DNS entry.
    3 Replace <role-name> with the name of the role which will be created (for example: saagie_job_role).
    4 Replace <policy-arn> with the ARN of the policy chosen for Saagie jobs.
  3. Make the file executable with the following command:

    chmod +x create-job-role.sh
  4. Launch the creation of the role by executing the script file:

    ./create-job-role.sh
  5. After running the script, the ARN of the role you created will be printed in the output.

    Note the ARN; you’ll need it when configuring your instance.
Next step

After creating or configuring your cluster, continue to Prepare your Kubernetes cluster.