Installing Che 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 Che on Microsoft Azure.

Preparing Azure for installing Che

Procedure

To set up the Azure environment for Che:

Install the Azure command-line tool. For details, see Install the Azure CLI.

For example, on macOS:
```
$ brew update && brew install azure-cli
```
Log in to Azure:
```
$ az login
```

Create an Azure group (to list the locations, use the az account list-locations command):

$ az group create --name eclipseCheResourceGroup --location francecentral
{
  "id": "/subscriptions/ab0f7986-a280-481c-a47d-98fa45ff94ca/resourceGroups/eclipseCheResourceGroup",
  "location": "francecentral",
  "managedBy": null,
  "name": "eclipseCheResourceGroup",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": null
}

Create the cluster:

$ az aks create --resource-group eclipseCheResourceGroup \
  --name eclipse-che --node-count 1 --enable-addons monitoring --generate-ssh-keys

Configure kubectl:

$ az aks get-credentials --name eclipse-che --resource-group eclipseCheResourceGroup
Merged "eclipse-che" as current context in /Users/benoitf/.kube/config

Check the Kubernetes context:

$ kubectl config current-context
eclipse-che

$ kubectl get pods --all-namespaces

All the Pods in the running state are displayed.

Installing Ingress on Kubernetes

Eclipse Che uses Ingress.

Procedure

To install Ingress-nginx:

Install the cloud configuration:

$ kubectl apply \
  -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.41.0/deploy/static/provider/cloud/deploy.yaml

The following output confirms that the Ingress controller is running:

$ kubectl get pods --namespace ingress-nginx
NAME                                        READY   STATUS    RESTARTS   AGE
nginx-ingress-controller-76c86d76c4-gswmg   1/1     Running   0          9m3s

Wait for the container to run.

Wait for the external IP. Note that a <pending> status for the external IP is shown before the exact external IP address is displayed.

$ kubectl get services  --namespace ingress-nginx
NAME           TYPE          CLUSTER-IP   EXTERNAL-IP    PORT(S)                     AGE
ingress-nginx  LoadBalancer  10.0.97.244  40.89.129.194  80:31107/TCP,443:30629/TCP  8m59s

Get the external IP of Ingress-nginx.

$ kubectl get services --namespace ingress-nginx \
  -o jsonpath='{.items[].status.loadBalancer.ingress[0].ip}'
40.89.129.194

Configuring DNS on Azure

Procedure

To configure DNS on Azure:

In the Azure web console, navigate to Home → DNS zones.
Create a new zone.
1. In the Resource group drop-down list, click eclipseCheResourceGroup.
2. In the Instance details section, in the Name field, type the name of the domain (azr.my-ide.cloud, in this case).
3. Click the Review + create button.
Click the Create button.

The created zone and the list of name servers (NS) are displayed in the DNS Zones section.

These servers must be configured with the registrar of the domain.
Navigate to the Azure DNS zone, and click the + Record set button ().
To add a record set:
1. In the Name field, type *.
2. In the IP Address field, select the external IP of Ingress-nginx controller that the user had obtained in the Installing Ingress on Kubernetes section (40.89.129.194, in this case).
  
  The following is an example of an added DNS zone:

Enabling the TLS and DNS challenge on Azure

To use Azure DNS and TLS, permissions must be granted to have cert-manager managing the DNS challenge for the Let’s Encrypt service.

Procedure

Set the variable for the domain:

AZURE_CERT_MANAGER_DNS_NAME=azr.my-ide.cloud

Generate the secrets:

AZURE_CERT_MANAGER_SP_APP_ID=$(az ad sp create-for-rbac --name cert-manager-eclipse-che --query "appId" --output tsv)
AZURE_CERT_MANAGER_SP_PASSWORD=$(az ad sp create-for-rbac --name cert-manager-eclipse-che --query "password" --output tsv)

Lower the permissions of the service principal (SP):

$ az role assignment delete --assignee $AZURE_CERT_MANAGER_SP_APP_ID --role Contributor

Give access to the DNS zone:

DNS_ID=$(az network dns zone show --name $AZURE_CERT_MANAGER_DNS_NAME --resource-group eclipseCheResourceGroup --query "id" --output tsv)

$ az role assignment create --assignee $AZURE_CERT_MANAGER_SP_APP_ID \
  --role "DNS Zone Contributor" --scope $DNS_ID

Check the permissions:

$ az role assignment list --assignee $AZURE_CERT_MANAGER_SP_APP_ID

Get the Service Principal App ID and password for the configuration:

$ echo ID=$AZURE_CERT_MANAGER_SP_APP_ID
$ echo PASSWORD=$AZURE_CERT_MANAGER_SP_PASSWORD

Creating a Service Account Secret on Azure

The secret must be in the cert-manager namespace. Otherwise the secret cannot be found, and cert-manager reports errors.

Procedure

To create the secret, run the following command:

$ kubectl create secret generic azuredns-config \
  --from-literal=CLIENT_SECRET=$AZURE_CERT_MANAGER_SP_PASSWORD -n cert-manager

Installing cert-manager on Azure

Prerequisites

The kubectl tool is available.

Procedure

To install the cert-manager on Azure, create the cert-manager namespace:

$ {orch-cli} create namespace cert-manager
namespace/cert-manager created

$ {orch-cli} label namespace cert-manager certmanager.k8s.io/disable-validation=true

$ {orch-cli} apply \
  -f https://github.com/jetstack/cert-manager/releases/download/v0.15.0/cert-manager.yaml

$ {orch-cli} apply \
 --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.0/cert-manager.crds.yaml

Create the che namespace if it does not already exist:

$ kubectl create namespace eclipse-che
namespace/eclipse-che created

Create the certificate issuer. Enter your email address in the email field and set clientID, CLIENT_SECRET subscriptionID, tenantID, hostedZoneName fields:

cat <<EOF | {orch-cli} apply -f -
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: che-certificate-issuer
spec:
  acme:
    solvers:
    - dns01:
        azuredns:
          # Service principal clientId (It's the value printed in the previous lines: echo ID=$AZURE_CERT_MANAGER_SP_APP_ID )
          clientID: <AZURE_CERT_MANAGER_SP_APP_ID>
          # A secretKeyRef to a service principal ClientSecret (password)
          # ref: https://docs.microsoft.com/en-us/azure/container-service/kubernetes/container-service-kubernetes-service-principal
          clientSecretSecretRef:
            name: azuredns-config
            # CLIENT_SECRET is the value of AZURE_CERT_MANAGER_SP_PASSWORD
            key: <CLIENT_SECRET>
          # Azure subscription Id that can be obtained with command:
          # $ az account show  | jq -r '.id'
          subscriptionID: <SUBSCRIPTION_ID>
          # Azure AD tenant Id that can be obtained with command:
          # $ az account show  | jq -r '.tenantId'
          tenantID: <TENANT_ID>
          resourceGroupName: eclipseCheResourceGroup
          # The DNS Zone to use
          hostedZoneName: azr.my-ide.cloud
    email: florent@example.com
    privateKeySecretRef:
      name: letsencrypt
    server: https://acme-v02.api.letsencrypt.org/directory
EOF

Create the certificate. Edit the domain name:

cat <<EOF | {orch-cli} apply -f -
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
 name: che-tls
 namespace: {prod-namespace}
spec:
 secretName: che-tls
 issuerRef:
   name: che-certificate-issuer
   kind: ClusterIssuer
 dnsNames:
   - '*.azr.my-ide.cloud'
EOF

Check that the issuerRef name is the same as the ClusterIssuer. A new DNS challenge is added to the DNS zone for Let’s Encrypt.

The cert-manager logs contain information about the DNS challenge.
Obtain the logs using the following command (here, cert-manager-8d478bb45-2924h is the name of the cert-manager Pod):
```
$  {orch-cli} logs -f -n cert-manager cert-manager-8d478bb45-2924h
```

Ensure that the certificate is ready:

$ kubectl describe certificate/che-tls -n eclipse-che

Status:
  Conditions:
    Last Transition Time:  2019-07-29T13:50:35Z
    Message:               Certificate issuance in progress. Temporary certificate issued.
    Reason:                TemporaryCertificate
    Status:                False
    Type:                  Ready

Events:
  Type    Reason              Age   From          Message
  ----    ------              ----  ----          -------
  Normal  Generated           47s   cert-manager  Generated new private key
  Normal  GenerateSelfSigned  47s   cert-manager  Generated temporary self signed certificate
  Normal  OrderCreated        47s   cert-manager  Created Order resource "che-tls-3529929423”

Wait for the status to show OK and ensure that the log contains the following:

$ {orch-cli} describe certificate/che-tls -n {prod-namespace}
Name:         che-tls
Namespace:    che
Labels:       <none>
Annotations:  API Version:  cert-manager.io/v1alpha3
Kind:         Certificate
Metadata:
  Creation Timestamp:  2020-07-29T10:32:49Z
  Generation:          1
  Resource Version:    7961
  Self Link:           /apis/cert-manager.io/v1alpha3/namespaces/che/certificates/che-tls
  UID:                 2034c6d5-bce3-4ce8-8489-df31d02b84e9
Spec:
  Dns Names:
    *.azr.my-ide.cloud
  Issuer Ref:
    Kind:       ClusterIssuer
    Name:       che-certificate-issuer
  Secret Name:  che-tls
Status:
  Conditions:
    Last Transition Time:  2020-07-29T10:35:05Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               2020-10-27T09:35:02Z
Events:
  Type    Reason        Age    From          Message
  ----    ------        ----   ----          -------
  Normal  GeneratedKey  5m49s  cert-manager  Generated a new private key
  Normal  Requested     5m49s  cert-manager  Created new CertificateRequest resource "che-tls-2082883576"
  Normal  Issued        3m34s  cert-manager  Certificate issued successfully

Installing Che on Microsoft Azure using chectl

Prerequisites

The chectl management tool is available. See Using the chectl management tool.
The helm tool is available, with version 2.15 or higher. See Helm.

Procedure

To install Che on Microsoft Azure, run the following chectl command:

$ chectl server:deploy --installer=helm --platform=k8s --domain=azr.my-ide.cloud --multiuser
› Current Kubernetes context: 'minikube'
  ✔ Verify Kubernetes API...OK
  ✔ 👀  Looking for an already existing Eclipse Che instance
    ✔ Verify if Eclipse Che is deployed into namespace "eclipse-che"...it is not
  ✔ ✈️  Kubernetes preflight checklist
    ✔ Verify if kubectl is installed
    ✔ Verify remote kubernetes status...done.
    ✔ Check Kubernetes version: Found v1.15.12-gke.2.
    ✔ Verify domain is set...set to azr.my-ide.cloud.
    ↓ Check if cluster accessible [skipped]
  ✔ Following Eclipse Che logs
    ↓ Start following Operator logs [skipped]
    ✔ Start following Eclipse Che server logs...done
    ✔ Start following Postgres logs...done
    ✔ Start following Keycloak logs...done
    ✔ Start following Plugin registry logs...done
    ✔ Start following Devfile registry logs...done
    ✔ Start following namespace events...done
  ✔ 🏃‍  Running Helm to install Eclipse Che
    ✔ Verify if helm is installed
    ✔ Check Helm Version: Found v3.4.1+gc4e7485
    ✔ Create Namespace (eclipse-che)...does already exist.
    ✔ Check Eclipse Che TLS certificate...self-signed TLS certificate secret found
    ✔ Check Cluster Role Binding...does not exists.
    ✔ Preparing Eclipse Che Helm Chart...done.
    ✔ Updating Helm Chart dependencies...done.
    ✔ Deploying Eclipse Che Helm Chart...done.
  ✔ ✅  Post installation checklist
    ✔ PostgreSQL pod bootstrap
      ✔ Scheduling...done
      ✔ Downloading images...done
      ✔ Starting...done
    ✔ Devfile registry pod bootstrap
      ✔ Scheduling...done
      ✔ Downloading images...done
      ✔ Starting...done
    ✔ Plugin registry pod bootstrap
      ✔ Scheduling...done
      ✔ Downloading images...done
      ✔ Starting...done
    ✔ Eclipse Che pod bootstrap
      ✔ Scheduling...done
      ✔ Downloading images...done
      ✔ Starting...done
    ✔ Eclipse Che status check...done
  ✔ Prepare post installation output...done
  ✔ Show important messages
    ✔ Eclipse Che 7.23 has been successfully deployed.
    ✔ Documentation             : https://www.eclipse.org/che/docs
    ✔ -------------------------------------------------------------------------------
    ✔ Users Dashboard           : https://eclipse-che-eclipse-che.azr.my-ide.cloud
    ✔ Admin user login          : "XXX:XXX". NOTE: must change after first login.
    ✔ -------------------------------------------------------------------------------
    ✔ Plug-in Registry          : https://plugin-registry-eclipse-che.azr.my-ide.cloud/v3
    ✔ Devfile Registry          : https://devfile-registry-eclipse-che.azr.my-ide.cloud
    ✔ -------------------------------------------------------------------------------
    ✔ Identity Provider URL     : https://keycloak-eclipse-che.azr.my-ide.cloud/auth
    ✔ Identity Provider login   : "XXX:XXX".
    ✔ -------------------------------------------------------------------------------

Verification steps

Investigate Eclipse Che logs:

$ chectl server:logs --namespace eclipse-che

Verify that certificates are set correctly
1. Open Eclipse Che server URL from the output above
2. Click on the lock in address bar
3. Verify it has Connection is secure

Additional resources

Navigating Che using the Dashboard.