From db06e09472bd13b583b228dc71f543e5333936c8 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Wed, 27 Nov 2024 15:03:28 +0100 Subject: [PATCH] feat: Installing che on EKS Signed-off-by: Anatolii Bazko --- antora.yml | 2 + .../examples/snip_che-installing-che.adoc | 1 + modules/administration-guide/nav.adoc | 1 + .../pages/installing-che-in-the-cloud.adoc | 1 + ...-on-amazon-elastic-kubernetes-service.adoc | 35 ++++ ...for-amazon-elastic-kubernetes-service.adoc | 39 ++++ ...-on-amazon-elastic-kubernetes-service.adoc | 113 +++++++++++ ...-on-amazon-elastic-kubernetes-service.adoc | 174 +++++++++++++++++ ...-on-amazon-elastic-kubernetes-service.adoc | 24 +++ ...-on-amazon-elastic-kubernetes-service.adoc | 55 ++++++ ...on-microsoft-azure-kubernetes-service.adoc | 1 - ...-on-amazon-elastic-kubernetes-service.adoc | 62 ++++++ ...-on-amazon-elastic-kubernetes-service.adoc | 182 ++++++++++++++++++ 13 files changed, 689 insertions(+), 1 deletion(-) create mode 100644 modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_installing-cert-manager-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc create mode 100644 modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc diff --git a/antora.yml b/antora.yml index 381325d054..338c776f52 100644 --- 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 index 8a360e1f3a..8228f6048d 100644 --- 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 index a85fcb205c..7f312c2de0 100644 --- 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 index 24cc78d858..7f934307fd 100644 --- 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/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/pages/installing-che-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..a2fa7392b9 --- /dev/null +++ b/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] \ No newline at end of file diff --git a/modules/administration-guide/partials/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/configuring-environment-variables-for-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..2a21934fda --- /dev/null +++ b/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}] diff --git a/modules/administration-guide/partials/proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_configuring-dns-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..01954ff507 --- /dev/null +++ b/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 +---- \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..7dea1719ce --- /dev/null +++ b/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 <__ <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 `____` 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] + + diff --git a/modules/administration-guide/partials/proc_installing-cert-manager-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-cert-manager-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..baf85c63fb --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-cert-manager-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,24 @@ +[id="installing-cert-manager-on-amazon-elastic-kubernetes-service"] += Installing cert-manager on {eks-short} + +Use the following instructions to install the link:https://cert-manager.io[cert-manager] on {eks-short}. + +.Procedure + +. Install `cert-manager` using `Helm`: ++ +[source,subs="attributes+"] +---- +helm repo add jetstack https://charts.jetstack.io +helm repo update + +helm install cert-manager jetstack/cert-manager \ + --wait \ + --create-namespace \ + --namespace cert-manager \ + --set crds.enabled=true +---- + +.Additional resources + +* link:https://cert-manager.io/docs/tutorials/getting-started-aws-letsencrypt/[cert-manager Installation Guide] diff --git a/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..532720959e --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service + +[id="installing-che-on-amazon-elastic-kubernetes-service"] += Installing {prod-short} on {eks-short} + +Follow these instructions to install {prod-short} on {eks-short}. + +.Procedure + +. Prepare a CheCluster patch YAML file: ++ +[source,shell,subs="attributes+"] +---- +cat > che-cluster-patch.yaml << EOF +spec: + networking: + auth: + oAuthClientName: k8s-client + oAuthSecret: eclipse-che + identityProviderURL: "https://$KEYCLOAK_HOST/realms/che" + gateway: + oAuthProxy: + cookieExpireSeconds: 300 + deployment: + containers: + - env: + - name: OAUTH2_PROXY_BACKEND_LOGOUT_URL + value: "http://$KEYCLOAK_HOST/realms/che/protocol/openid-connect/logout?id_token_hint=\{id_token}" + name: oauth-proxy + components: + cheServer: + extraProperties: + CHE_OIDC_EMAIL__CLAIM: email +EOF +---- + +. Deploy {prod-short}: ++ +[source,subs="attributes+"] +---- +{prod-cli} server:deploy \ + --platform k8s \ + --domain $DOMAIN_NAME \ + --che-operator-cr-patch-yaml che-patch.yaml \ + --skip-cert-manager +---- + +. Navigate to the {prod-short} cluster instance: ++ +[subs="+attributes,+quotes"] +---- +{prod-cli} dashboard:open +---- diff --git a/modules/administration-guide/partials/proc_installing-che-on-microsoft-azure-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-che-on-microsoft-azure-kubernetes-service.adoc index 62fb692f9c..009f1cef9f 100644 --- a/modules/administration-guide/partials/proc_installing-che-on-microsoft-azure-kubernetes-service.adoc +++ b/modules/administration-guide/partials/proc_installing-che-on-microsoft-azure-kubernetes-service.adoc @@ -44,7 +44,6 @@ EOF chectl server:deploy \ --platform=k8s \ --che-operator-cr-patch-yaml=che-cluster-patch.yaml \ - --skip-oidc-provider-check \ --skip-cert-manager \ --domain=$DOMAIN_NAME ---- diff --git a/modules/administration-guide/partials/proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..ff01b40c57 --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// installing-{prod-id-short}-on-amazon-elastic-kubernetes-service + +[id="installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service"] += Installing Ingress-Nginx Controller on {eks-short} + +Use the following instructions to install the link:https://kubernetes.github.io/ingress-nginx/[Ingress-Nginx Controller] on {eks-short}. + +.Procedure + +. Install the `Ingress-Nginx Controller` using `Helm`: ++ +[source,subs="attributes+"] +---- +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update + +helm install ingress-nginx ingress-nginx/ingress-nginx \ + --wait \ + --create-namespace \ + --namespace ingress-nginx \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-backend-protocol"=tcp \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-cross-zone-load-balancing-enabled"="true" \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"=nlb +---- + +. Wait for the external IP: ++ +[source,subs="attributes+"] +---- +{orch-cli} get services ingress-nginx-controller --namespace ingress-nginx +---- +The output will be similar to: ++ +[source,subs="attributes+"] +---- +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +ingress-nginx-controller LoadBalancer 10.0.65.52 XXX.elb.amazonaws.com 80:32711/TCP,443:31294/TCP 75s +---- +. Verify that you can access the load balancer externally: ++ +[source,subs="attributes+"] +---- +until curl $({orch-cli} get service -n ingress-nginx ingress-nginx-controller -o=jsonpath='{.status.loadBalancer.ingress[0].hostname}'); do sleep 5s; done +---- +You should receive the output similar to: ++ +[source,html,subs="attributes+"] +---- + +404 Not Found + +

404 Not Found

+
nginx
+ + +---- + +.Additional resources + +* link:https://kubernetes.github.io/ingress-nginx/deploy/[Ingress-Nginx Controller Installation Guide] \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..9bc42038ee --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,182 @@ +[id="installing-keycloak-on-amazon-elastic-kubernetes-service"] += Installing Keycloak on {eks} + +Learn how to install https://www.keycloak.org/[Keycloak] as the OpenID Connect (OIDC) provider. + +.Procedure + +. Define Keycloak host name: ++ +[source,subs="+attributes"] +---- +KEYCLOAK_HOST=keycloak.$DOMAIN_NAME +---- + +. Install Keycloak: ++ +IMPORTANT: While this guide provides a development configuration for deploying Keycloak on {kubernetes}, keep in mind that production environments require different settings, for instance configuring external databases. ++ +[source,subs="+attributes"] +---- +{orch-cli} apply -f - <