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..55ff4ccc21 --- /dev/null +++ b/modules/administration-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] \ 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..cbc36ed0a9 --- /dev/null +++ b/modules/administration-guide/partials/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/modules/administration-guide/partials/proc_associate-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service.adoc b/modules/administration-guide/partials/proc_associate-keycloak-as-oidc-identity-provider-on-amazon-elastic-kubernetes-service.adoc new file mode 100644 index 0000000000..49af0f5253 --- /dev/null +++ b/modules/administration-guide/partials/proc_associate-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] \ No newline at end of file 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..1349bb647f --- /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} + +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 +---- \ 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..2cf7a75430 --- /dev/null +++ b/modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,172 @@ +// 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: '$CHE_DOMAIN_NAME' + dnsNames: + - '$CHE_DOMAIN_NAME' + - '*.$CHE_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..67af143e92 --- /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} + +Follow these 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..67f7f08bff --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-che-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,57 @@ +// 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_DOMAIN_NAME/realms/che" + gateway: + oAuthProxy: + cookieExpireSeconds: 300 + deployment: + containers: + - env: + - name: OAUTH2_PROXY_BACKEND_LOGOUT_URL + value: "http://$KEYCLOAK_DOMAIN_NAME/realms/che/protocol/openid-connect/logout?id_token_hint=\{id_token}" + name: oauth-proxy + components: + cheServer: + extraProperties: + CHE_OIDC_USERNAME__CLAIM: email +EOF +---- + +. Deploy {prod-short}: ++ +[source,subs="attributes+"] +---- +{prod-cli} server:deploy \ + --platform k8s \ + --domain $CHE_DOMAIN_NAME \ + --che-operator-cr-patch-yaml che-cluster-patch.yaml \ + --skip-cert-manager \ + --k8spodreadytimeout 240000 \ + --k8spoddownloadimagetimeout 240000 +---- + +. 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..1517b82981 --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-ingress-nginx-controller-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,50 @@ +// 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} + +Follow these 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 +---- + +. Verify that you can access the load balancer externally. +It may take a few minutes for the load balancer to be created: ++ +[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..9246e8cd9b --- /dev/null +++ b/modules/administration-guide/partials/proc_installing-keycloak-on-amazon-elastic-kubernetes-service.adoc @@ -0,0 +1,178 @@ +[id="installing-keycloak-on-amazon-elastic-kubernetes-service"] += Installing Keycloak on {eks} + +Follow these instructions to install https://www.keycloak.org/[Keycloak] as the OpenID Connect (OIDC) provider. + +.Procedure + +. Install Keycloak: ++ +[IMPORTANT] +==== + While this guide provides a development configuration for deploying Keycloak on {kubernetes}, remember that production environments might require different settings, such as external database configuration. +==== ++ +[source,subs="+attributes"] +---- +{orch-cli} apply -f - <