feat: Deploy Eclipse Che on AKS

modules/administration-guide/nav.adoc

@@ -18,6 +18,8 @@
 ** xref:installing-che-on-openshift-using-cli.adoc[]
 ** xref:installing-che-on-openshift-using-the-web-console.adoc[]
 ** xref:installing-che-in-a-restricted-environment.adoc[]
+** xref:installing-che-in-the-cloud.adoc[]
+*** xref:installing-che-on-microsoft-azure.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

@@ -0,0 +1,21 @@
+:_content-type: PROCEDURE
+:description: Installing {prod-short} in the cloud
+:keywords: overview, running-che-in-the-cloud, installing-che-in-the-cloud
+:navtitle: Installing {prod-short} in the cloud
+
+[id="installing-{prod-id-short}-locally"]
+= Installing {prod-short} in the cloud
+
+Deploy and run {prod} in the cloud.
+
+.Prerequisites
+
+* A {platforms-name} cluster to deploy {prod-short} on.
+
+* `{prod-cli}`: The command line tool for {prod}. See: xref:installing-the-chectl-management-tool.adoc[].
+
+== Deploying {prod-short} in the cloud
+
+Follow the instructions below to start the {prod-short} Server in the cloud using the `{prod-cli}` tool.
+
+* xref:installing-che-on-microsoft-azure.adoc[]

modules/administration-guide/pages/installing-che-on-microsoft-azure.adoc

@@ -0,0 +1,33 @@
+:_content-type: ASSEMBLY
+:description: Installing {prod-short} on Microsoft Azure
+:keywords: overview, installing-che-on-microsoft-azure
+:navtitle: Installing {prod-short} on Microsoft Azure
+
+[id="installing-{prod-id-short}-on-microsoft-azure"]
+= Installing {prod-short} on Microsoft Azure
+
+Microsoft Azure is a cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through Microsoft-managed data centers.
+
+This section provides information about installing, enabling, and basic use of {prod-short} on Microsoft Azure.
+
+.Prerequisites
+
+* `helm` the package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm].
+
+* `az` the Microsoft Azure CLI command line tool. See: link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[How to install Microsoft Azure CLI].
+
+* `kubelogin` the credential plugins See: link:https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-install-cli[How to install kubelogin].
+
+include::partial$proc_preparing-microsoft-azure-for-installing-che.adoc[leveloffset=+1]
+
+include::partial$proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-dns-on-microsoft-azure.adoc[leveloffset=+1]
+
+include::partial$proc_creating-lets-encrypt-certificate-for-che-on-microsoft-azure.adoc[leveloffset=+1]
+
+include::partial$proc_registering-application-on-microsoft-azure.adoc[leveloffset=+1]
+
+include::partial$proc_installing-che-on-microsoft-azure-kubernetes-service.adoc[leveloffset=+1]

modules/administration-guide/partials/proc_configuring-dns-on-microsoft-azure.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-microsoft-azure
+
+[id="configuring-DNS-on-microsoft-azure"]
+= Configuring DNS on Microsoft Azure
+
+.Procedure
+
+. Define the domain name. You will need to register a domain unless you already have one.
++
+[source,shell]
+----
+export DOMAIN_NAME=azr.my-ide.cloud
+----
+
+. Create a DNS zone:
++
+[source,shell]
+----
+az network dns zone create \
+  --resource-group $ECLIPSE_CHE_RESOURCE_GROUP \
+  --name $DOMAIN_NAME
+----
+
+. Create a DNS record set:
++
+[source,shell,subs="attributes+"]
+----
+az network dns record-set a add-record \
+  --resource-group $ECLIPSE_CHE_RESOURCE_GROUP \
+  --zone-name $DOMAIN_NAME \
+  --record-set-name "*" \
+  --ipv4-address $({orch-cli} get service -n ingress-nginx ingress-nginx-controller -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')
+----
+IMPORTANT: If you use a registrar such as GoDaddy, you will need to add
+two DNS records in your registrar of type `A`, names `@` and `*` and point them to the
+IP address of the ingress controller.
++
+.Additional resources
+
+* link:https://learn.microsoft.com/en-us/azure/dns/dns-getstarted-cli[Create a Microsoft Azure DNS zone and record using Microsoft Azure CLI]

modules/administration-guide/partials/proc_creating-lets-encrypt-certificate-for-che-on-microsoft-azure.adoc

@@ -0,0 +1,108 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-microsoft-azure
+
+[id="creating-lets-encrypt-certificate-for-{prod-id-short}-on-microsoft-azure"]
+= Creating Let's encrypt certificate for {prod-id-short} on Microsoft Azure
+
+.Procedure
+
+. Create a service principal:
++
+[source,shell,subs="attributes+"]
+----
+CERT_MANAGER_SERVICE_PRINCIPAL_NAME=cert-manager-eclipse-che
+CERT_MANAGER_SERVICE_PRINCIPAL_APP_ID=$(az ad sp create-for-rbac --name $CERT_MANAGER_SERVICE_PRINCIPAL_NAME --query "appId" --output tsv)
+----
+
+. Give access to the DNS zone:
++
+[source,shell,subs="attributes+"]
+----
+az role assignment create \
+  --assignee $CERT_MANAGER_SERVICE_PRINCIPAL_APP_ID \
+  --scope $(az network dns zone show --name $DOMAIN_NAME --resource-group $ECLIPSE_CHE_RESOURCE_GROUP --query "id" --output tsv) \
+  --role "DNS Zone Contributor"
+----
+
+. Create the {prod-namespace} namespace:
++
+[source,shell,subs="attributes+"]
+----
+{orch-cli} create namespace {prod-namespace}
+----
+
+. Creating a Service Account Secret:
++
+[source,shell,subs="attributes+"]
+----
+{orch-cli} create secret generic azuredns-config \
+  --from-literal=clientSecret=$(az ad sp create-for-rbac --name $CERT_MANAGER_SERVICE_PRINCIPAL_NAME --query "password" --output tsv) \
+  --namespace {prod-namespace}
+----
+
+. Create the Issuer. Replace `MY_EMAIL_ADDRESS` with a valid address:
++
+[source,shell,subs="+attributes,+quotes"]
+----
+{orch-cli} apply -f - << EOF
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: {prod-id-short}-letsencrypt
+  namespace: {prod-namespace}
+spec:
+  acme:
+    solvers:
+    - dns01:
+        azureDNS:
+          clientID: $CERT_MANAGER_SERVICE_PRINCIPAL_APP_ID
+          clientSecretSecretRef:
+            name: azuredns-config
+            key: clientSecret
+          subscriptionID: $(az account show --query "id" --output tsv)
+          tenantID: $(az account show --query "tenantId" --output tsv)
+          resourceGroupName: $ECLIPSE_CHE_RESOURCE_GROUP
+          hostedZoneName: $DOMAIN_NAME
+    email: `__MY_EMAIL_ADDRESS__`
+    privateKeySecretRef:
+      name: letsencrypt
+    server: https://acme-v02.api.letsencrypt.org/directory
+EOF
+----
+
+. Create the Certificate:
++
+[source,shell,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: Issuer
+  commonName: '$DOMAIN_NAME'
+  dnsNames:
+  - '$DOMAIN_NAME'
+  - '*.$DOMAIN_NAME'
+  usages:
+    - server auth
+    - digital signature
+    - key encipherment
+    - key agreement
+    - data encipherment
+EOF
+----
+IMPORTANT: If you use a registrar such as GoDaddy, you will need to duplicate DNS records in your registrar of
+type `TXT` and name `_acme-challenge`.
++
+.Additional resources
+
+* link:https://cert-manager.io/docs/tutorials/getting-started-aks-letsencrypt[Deploy cert-manager on Azure Kubernetes Service (AKS) and use Let's Encrypt to sign a certificate for an HTTPS website]
+
+

modules/administration-guide/partials/proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-microsoft-azure
+
+[id="installing-cert-manager-on-microsoft-azure-kubernetes-service"]
+= Installing cert-manager on Microsoft Azure Kubernetes Service
+
+.Procedure
+
+. To install the cert-manager:
++
+[source,shell,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 installCRDs=true
+----
+
+.Additional resources
+
+* link:https://learn.microsoft.com/en-us/azure/aks/ingress-tls[Use TLS with an ingress controller on Azure Kubernetes Service (AKS)]

modules/administration-guide/partials/proc_installing-che-on-microsoft-azure-kubernetes-service.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-microsoft-azure
+
+[id="installing-che-on-microsoft-azure-kubernetes-service"]
+= Installing {prod-short} on Microsoft Azure Kubernetes Service
+
+.Procedure
+
+. Prepare a CheCluster patch YAML file:
++
+[source,shell,subs="attributes+"]
+----
+cat > che-cluster-patch.yaml << EOF
+spec:
+  networking:
+    auth:
+      identityProviderURL: "https://sts.windows.net/$(az account show --query "tenantId" --output tsv)/v2.0/"
+      identityToken: access_token
+      oAuthClientName: $(az ad app list --query "[?displayName=='$ECLIPSE_CHE_APPLICATION_DISPLAY_NAME'].appId" --output tsv)
+      oAuthSecret: $(az ad app credential reset --id $ECLIPSE_CHE_APPLICATION_ID --query "password" --output tsv)
+      oAuthScope: openid email profile 6dae42f8-4368-4678-94ff-3960e28e3630/user.read
+      gateway:
+        deployment:
+          containers:
+          - env:
+            - name: OAUTH2_PROXY_INSECURE_OIDC_ALLOW_UNVERIFIED_EMAIL
+              value: "true"
+            name: oauth-proxy
+  components:
+    cheServer:
+      extraProperties:
+        CHE_OIDC_AUTH__SERVER__URL: "https://sts.windows.net/$(az account show --query "tenantId" --output tsv)/v2.0/"
+        CHE_OIDC_EMAIL__CLAIM: unique_name
+EOF
+----
+
+. Deploy {prod-short}:
++
+[source,shell,subs="attributes+"]
+----
+chectl server:deploy \
+       --platform=k8s \
+       --che-operator-cr-patch-yaml=che-cluster-patch.yaml \
+       --skip-oidc-provider-check \
+       --skip-cert-manager \
+       --domain=$DOMAIN_NAME
+----
+
+. Navigate to the {prod-short} cluster instance:
++
+[subs="+attributes,+quotes"]
+----
+$ {prod-cli} dashboard:open
+----
+
+
+.Additional resources
+
+* https://che.eclipseprojects.io/2022/07/25/@karatkep-installing-eclipse-che-on-aks.html[Installing Eclipse Che on the Azure Kubernetes Service (AKS)]

modules/administration-guide/partials/proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-on-microsoft-azure
+
+[id="installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service"]
+= Installing NGINX Ingress Controller on Microsoft Azure Kubernetes Service
+
+.Procedure
+
+. Install NGINX Ingress Controller:
++
+[source,shell,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/azure-load-balancer-health-probe-request-path"=/healthz
+----
+
+. Wait for the external IP. Note that a `<pending>` status for the external IP is shown before the exact external IP address is displayed.
++
+[source,shell,subs="attributes+"]
+----
+{orch-cli} get services ingress-nginx-controller --namespace ingress-nginx
+NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
+ingress-nginx-controller             LoadBalancer   10.0.65.52     XX.XXX.XX.XXX   80:31104/TCP,443:32552/TCP   13m
+----
+
+.Additional resources
+
+* link:https://learn.microsoft.com/en-us/azure/aks/ingress-basic[Create an unmanaged ingress controller]