feat: Installing che on EKS

Signed-off-by: Anatolii Bazko <[email protected]>

antora.yml

@@ -110,6 +110,8 @@ asciidoc:
     theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next
     editor-definition-samples-link: link:https://github.com/eclipse-che/che-operator/tree/main/editors-definitions[Editors definitions samples]
     devfile-api-version: 2.3.0
+    eks: Amazon Elastic Kubernetes Service
+    eks-short: Amazon EKS
 ext:
   collector:
   - run:

modules/administration-guide/examples/snip_che-installing-che.adoc

@@ -14,6 +14,7 @@ You can deploy only one instance of {prod-short} per cluster.
 * xref:installing-che-on-openshift-using-the-web-console.adoc[]
 * xref:installing-che-in-a-restricted-environment.adoc[]
 * xref:installing-che-on-microsoft-azure.adoc[]
+* xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]
 
 .Installing {prod-short} on a local single-node cluster
 

modules/administration-guide/nav.adoc

@@ -21,6 +21,7 @@
 *** xref:installing-che-on-openshift-using-the-web-console.adoc[]
 *** xref:installing-che-in-a-restricted-environment.adoc[]
 *** xref:installing-che-on-microsoft-azure.adoc[]
+*** xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]
 ** xref:installing-che-locally.adoc[]
 *** xref:installing-che-on-red-hat-openshift-local.adoc[]
 *** xref:installing-che-on-minikube.adoc[]

modules/administration-guide/pages/installing-che-in-the-cloud.adoc

@@ -22,3 +22,4 @@ Follow the instructions below to start the {prod-short} Server in the cloud by u
 * xref:installing-che-on-openshift-using-the-web-console.adoc[]
 * xref:installing-che-in-a-restricted-environment.adoc[]
 * xref:installing-che-on-microsoft-azure.adoc[]
+* xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc

@@ -0,0 +1,35 @@
+:_content-type: ASSEMBLY
+:description: Installing {prod-short} on {eks}
+:keywords: overview, installing-{prod-id-short}-on-amazon-elastic-kubernetes-service.adoc
+:navtitle: Installing {prod-short} on {eks}
+
+[id="installing-{prod-id-short}-on-amazon-elastic-kubernetes-service.adoc"]
+= Installing {prod-short} on {eks}
+
+{eks} (Amazon EKS) is a managed {kubernetes} service to run {kubernetes} in the AWS cloud and on-premises data centers.
+
+Follow the instructions below to install and enable {prod-short} on {eks-short}.
+
+.Prerequisites
+
+* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm].
+
+* `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[].
+
+* `aws`: The AWS Command Line Interface. See: link:https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html[AWS CLI install and update instructions]
+
+* `eksctl`: The Command Line Interface for creating and managing {kubernetes} clusters on {eks-short}. See: link:https://eksctl.io/installation/[Installing eksctl]
+
+include::partial$configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-cert-manager-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-che-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]

modules/administration-guide/partials/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service
+
+[id="configuring-environment-variables-for-amazon-elastic-kubernetes-service"]
+= Configuring environment variables for {eks-short}
+
+Follow this guide to define environment variables and update your `kubeconfig` to connect to {eks-short}.
+
+.Prerequisites
+
+* Amazon EKS cluster. See: link:https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html[Create an Amazon EKS cluster]
+
+.Procedure
+
+. Define the cluster name:
++
+[source,subs="attributes+"]
+----
+CHE_EKS_CLUSTER_NAME=che
+----
+
+. Define the region:
++
+[source,subs="attributes+"]
+----
+CHE_EKS_CLUSTER_REGION=eu-central-1
+----
+
+. Update `kubeconfig`:
++
+[source,subs="attributes+"]
+----
+aws eks update-kubeconfig --region $CHE_EKS_CLUSTER_REGION --name $CHE_EKS_CLUSTER_NAME
+----
+
+.Additional resources
+
+* link:https://aws.amazon.com/eks/[{eks}]

modules/administration-guide/partials/proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc

@@ -0,0 +1,113 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service
+
+[id="configuring-DNS-on-amazon-elastic-kubernetes-service"]
+= Configuring DNS on {eks-short}
+
+Configure DNS on {eks-short}.
+
+.Prerequisites
+
+* A registered domain. See: link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html[Registering a new domain on {eks-short}].
+
+.Procedure
+
+. Define the previously registered domain name:
++
+[source,shell]
+----
+DOMAIN_NAME=eclipse-che-eks-clould.click
+----
+
+. Define domain name for Keycloak OIDC provider:
++
+[source,shell]
+----
+KEYCLOAK_DOMAIN_NAME=keycloak.$DOMAIN_NAME
+----
+
+. Find out the hosted zone ID for the domain:
++
+[source,shell]
+----
+HOSTED_ZONE_ID=$(aws route53 list-hosted-zones-by-name --dns-name $DOMAIN_NAME --query "HostedZones[0].Id" --output text)
+----
+
+. Find out the Canonical Hosted Zone ID for the load balancer:
++
+[source,shell]
+----
+CANONICAL_HOSTED_ZONE_ID=$(aws elbv2 describe-load-balancers --query "LoadBalancers[0].CanonicalHostedZoneId" --output text)
+----
+
+. Find out the DNS name for the load balancer:
++
+[source,shell]
+----
+DNS_NAME=$({orch-cli} get service -n ingress-nginx ingress-nginx-controller -o=jsonpath='{.status.loadBalancer.ingress[0].hostname}')
+----
+
+. Create a DNS record set:
++
+[source,subs="attributes+"]
+----
+aws route53 change-resource-record-sets \
+  --hosted-zone-id $HOSTED_ZONE_ID \
+  --change-batch '
+  {
+    "Comment": "Ceating a record set",
+     "Changes": [{
+      "Action"              : "CREATE",
+       "ResourceRecordSet"  : {
+         "Name"              : "'"$DOMAIN_NAME"'",
+         "Type"             : "A",
+         "AliasTarget"      : {
+            "HostedZoneId"            : "'"$CANONICAL_HOSTED_ZONE_ID"'",
+            "DNSName"                 : "'"$DNS_NAME"'",
+            "EvaluateTargetHealth"    : false
+        }
+      }
+    }]
+  }
+  '
+----
+
+. Verify that you can access the domain externally:
++
+[source,subs="attributes+"]
+----
+until curl $DOMAIN_NAME; do sleep 5s; done
+----
+
+. Create a DNS record set:
++
+[source,subs="attributes+"]
+----
+aws route53 change-resource-record-sets \
+  --hosted-zone-id $HOSTED_ZONE_ID \
+  --change-batch '
+  {
+    "Comment": "Ceating a record set",
+     "Changes": [{
+      "Action"              : "CREATE",
+       "ResourceRecordSet"  : {
+         "Name"              : "'"KEYCLOAK_DOMAIN_NAME"'",
+         "Type"             : "A",
+         "AliasTarget"      : {
+            "HostedZoneId"            : "'"$CANONICAL_HOSTED_ZONE_ID"'",
+            "DNSName"                 : "'"$DNS_NAME"'",
+            "EvaluateTargetHealth"    : false
+        }
+      }
+    }]
+  }
+  '
+----
+
+. Verify that you can access the Keycloak domain externally:
++
+[source,subs="attributes+"]
+----
+until curl $KEYCLOAK_DOMAIN_NAME; do sleep 5s; done
+----

modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc

@@ -0,0 +1,174 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service
+
+[id="creating-lets-encrypt-certificate-for-{prod-id-short}-on-amazon-elastic-kubernetes-service"]
+= Creating Let's Encrypt certificate for {prod-short} on {eks-short}
+
+Follow these instructions to create a Let's Encrypt certificate for {prod-short} on {eks-short}.
+
+.Procedure
+
+. Create an IAM OIDC provider:
++
+[source,subs="attributes+"]
+----
+eksctl utils associate-iam-oidc-provider --cluster $CHE_EKS_CLUSTER_NAME --approve
+----
+
+. Create a service principal:
++
+[source,subs="attributes+"]
+----
+aws iam create-policy \
+     --policy-name cert-manager-acme-dns01-route53 \
+     --description "This policy allows cert-manager to manage ACME DNS01 records in Route53 hosted zones. See https://cert-manager.io/docs/configuration/acme/dns01/route53" \
+     --policy-document file:///dev/stdin <<EOF
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "route53:GetChange",
+      "Resource": "arn:aws:route53:::change/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "route53:ChangeResourceRecordSets",
+        "route53:ListResourceRecordSets"
+      ],
+      "Resource": "arn:aws:route53:::hostedzone/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": "route53:ListHostedZonesByName",
+      "Resource": "*"
+    }
+  ]
+}
+EOF
+----
+
+. Create an IAM role and associate it with a Kubernetes Service Account:
++
+[source,subs="attributes+"]
+----
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
+
+eksctl create iamserviceaccount \
+  --name cert-manager-acme-dns01-route53 \
+  --namespace cert-manager \
+  --cluster $CHE_EKS_CLUSTER_NAME \
+  --role-name cert-manager-acme-dns01-route53 \
+  --attach-policy-arn arn:aws:iam::$AWS_ACCOUNT_ID:policy/cert-manager-acme-dns01-route53 \
+  --approve
+----
+
+. Grant permission for `cert-manager` to create Service Account tokens:
++
+[source,subs="attributes+"]
+----
+{orch-cli} apply -f - << EOF
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: cert-manager-acme-dns01-route53-tokenrequest
+  namespace: cert-manager
+rules:
+  - apiGroups: ['']
+    resources: ['serviceaccounts/token']
+    resourceNames: ['cert-manager-acme-dns01-route53']
+    verbs: ['create']
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: cert-manager-acme-dns01-route53-tokenrequest
+  namespace: cert-manager
+subjects:
+  - kind: ServiceAccount
+    name: cert-manager
+    namespace: cert-manager
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: cert-manager-acme-dns01-route53-tokenrequest
+EOF
+----
+
+. Create the Issuer:
++
+[source,subs="+attributes,+quotes"]
+----
+{orch-cli} apply -f - << EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: {prod-id-short}-letsencrypt
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: __<email_address>__ <1>
+    privateKeySecretRef:
+      name: {prod-id-short}-letsencrypt-production
+    solvers:
+    - dns01:
+        route53:
+          region: $CHE_EKS_CLUSTER_REGION
+          role: arn:aws:iam::$\{AWS_ACCOUNT_ID}:role/cert-manager-acme-dns01-route53
+          auth:
+            kubernetes:
+              serviceAccountRef:
+                name: cert-manager-acme-dns01-route53
+EOF
+----
+<1> Replace `__<email_address>__` with your email address.
+
+. Create the {prod-namespace} namespace:
++
+[source,subs="attributes+"]
+----
+{orch-cli} create namespace {prod-namespace}
+----
+
+. Create the Certificate:
++
+[source,subs="+attributes,+quotes"]
+----
+{orch-cli} apply -f - << EOF
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: che-tls
+  namespace: {prod-namespace}
+spec:
+  secretName: che-tls
+  issuerRef:
+    name: {prod-id-short}-letsencrypt
+    kind: ClusterIssuer
+  commonName: '$DOMAIN_NAME'
+  dnsNames:
+  - '$DOMAIN_NAME'
+  - '*.$DOMAIN_NAME'
+  usages:
+    - server auth
+    - digital signature
+    - key encipherment
+    - key agreement
+    - data encipherment
+EOF
+----
+
+. Wait for the `che-tls` secret to be created:
++
+[source,subs="attributes+"]
+----
+until {orch-cli} get secret -n {prod-namespace} che-tls; do sleep 5s; done
+----
+
+.Additional resources
+
+* link:https://cert-manager.io/docs/tutorials/getting-started-aws-letsencrypt/[cert-manager Installation Guide]
+
+