feat: Installing che on EKS (#2828)

* feat: Installing che on EKS Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> * Update modules/administration-guide/partials/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Update modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc Co-authored-by: Jana Vrbkova <[email protected]> * Fixup Signed-off-by: Anatolii Bazko <[email protected]> --------- Signed-off-by: Anatolii Bazko <[email protected]> Co-authored-by: Jana Vrbkova <[email protected]>
eclipse-che · Nov 29, 2024 · 9bc90d9 · 9bc90d9
1 parent 4fe3754
commit 9bc90d9
Show file tree

Hide file tree

Showing 14 changed files with 736 additions and 1 deletion.
diff --git a/antora.yml b/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:

diff --git a/modules/administration-guide/examples/snip_che-installing-che.adoc b/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
 

diff --git a/modules/administration-guide/nav.adoc b/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[]

diff --git a/modules/administration-guide/pages/installing-che-in-the-cloud.adoc b/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[]
diff --git a/...nistration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc b/...nistration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc
@@ -0,0 +1,37 @@
+:_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_associate-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-che-on-amazon-elastic-kubernetes-service.adoc[leveloffset=+1]
diff --git a/...ls/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc b/...ls/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc
@@ -0,0 +1,64 @@
+// 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 these instructions to define environment variables and update your `kubeconfig` to connect to {eks-short}.
+
+.Prerequisites
+
+* Amazon EKS cluster with storage addon. See: link:https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html[Create an Amazon EKS cluster]
+
+.Procedure
+
+. Find the AWS account ID:
++
+[source,subs="attributes+"]
+----
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
+----
+
+. 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
+----
+
+. Make sure that you have the default storage class set:
++
+[source,subs="attributes+"]
+----
+{orch-cli} get storageclass
+----
++
+The output should display a storage class with `default` next to its name:
++
+[source,subs="attributes+"]
+----
+NAME            PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
+gp2 (default)   kubernetes.io/aws-ebs   Delete          WaitForFirstConsumer   false                  126m
+----
+
+.Additional resources
+
+* link:https://aws.amazon.com/eks/[{eks}]
+* link:https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html[Store Kubernetes volumes with Amazon EBS]
+* link:https://docs.aws.amazon.com/eks/latest/userguide/create-managed-node-group.html[Create a managed node group for {eks-short}]
+* link:https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/[Change the default storage class on {kubernetes} cluster]
diff --git a/...te-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service.adoc b/...te-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service.adoc
@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service
+
+[id="associate-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service"]
+= Associate keycloak as OIDC identity provider on {eks-short}
+
+Follow these instructions to associate Keycloak an OIDC identity provider on {eks-short}.
+
+.Procedure
+
+. Associate Keycloak an identity provider using `eksctl`:
++
+[source,shell,subs="attributes+"]
+----
+eksctl associate identityprovider \
+  --wait \
+  --config-file - << EOF
+---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+metadata:
+  name: $CHE_EKS_CLUSTER_NAME
+  region: $CHE_EKS_CLUSTER_REGION
+identityProviders:
+  - name: keycloak-oidc
+    type: oidc
+    issuerUrl: https://$KEYCLOAK_DOMAIN_NAME/realms/che
+    clientId: k8s-client
+    usernameClaim: email
+EOF
+----
+
+.Additional resources
+
+* link:https://docs.aws.amazon.com/eks/latest/userguide/authenticate-oidc-identity-provider.html[Grant users access to {kubernetes} with an external OIDC provider]
diff --git a/...n-guide/partials/proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc b/...n-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}
+
+Follow these instructions to 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 registered domain name:
++
+[source,subs="attributes+"]
+----
+CHE_DOMAIN_NAME=eclipse-che-eks-clould.click
+----
+
+. Define domain name for Keycloak OIDC provider:
++
+[source,subs="attributes+"]
+----
+KEYCLOAK_DOMAIN_NAME=keycloak.$CHE_DOMAIN_NAME
+----
+
+. Find out the hosted zone ID for the domain:
++
+[source,subs="attributes+"]
+----
+HOSTED_ZONE_ID=$(aws route53 list-hosted-zones-by-name --dns-name $CHE_DOMAIN_NAME --query "HostedZones[0].Id" --output text)
+----
+
+. Find out the Canonical Hosted Zone ID for the load balancer:
++
+[source,subs="attributes+"]
+----
+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,subs="attributes+"]
+----
+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"              : "'"$CHE_DOMAIN_NAME"'",
+         "Type"             : "A",
+         "AliasTarget"      : {
+            "HostedZoneId"            : "'"$CANONICAL_HOSTED_ZONE_ID"'",
+            "DNSName"                 : "'"$DNS_NAME"'",
+            "EvaluateTargetHealth"    : false
+        }
+      }
+    }]
+  }
+  '
+----
+
+. Verify that you can access {prod-short} domain externally:
++
+[source,subs="attributes+"]
+----
+until curl $CHE_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
+----