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.

You need an Amazon Web Services (AWS) account.
Enable appropriate access keys and secret access keys.
Install kubectl.
Install the AWS CLI.
Configure the AWS CLI.
Install eksctl.

2. Create or configure cluster

Create new cluster
Configure existing cluster

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

Choose the eksctl method.
Confirm that the AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables are defined.

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.

Run the command:
```
eksctl create cluster -f cluster.yml
```

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.
Once your configuration file is created, check the connectivity.

Refer to the Kubernetes documentation if needed.

3. Verify your Kubernetes cluster

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`

Run the following command to apply your storage.yml file:
```
kubectl apply -f storage.yml
```
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.

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.
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.

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.

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.

Make the file executable with the following command:
```
chmod +x create-job-role.sh
```
Launch the creation of the role by executing the script file:
```
./create-job-role.sh
```
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.

Create Amazon EKS cluster

1. Prerequisites

2. Create or configure cluster

3. Verify your Kubernetes cluster

4. Create storage classes

4.1. Create a storage.yml file

4.2. Apply storage.yml

5. Install Calico

6. Set up a role for Saagie jobs

4.1. Create a `storage.yml` file

4.2. Apply `storage.yml`