Installing Che on Kind

This article explains how to deploy Che on a local kind Kubernetes cluster.

Installing Che on kind using chectl

This section describes how to install Che on kind using chectl. kind is a tool for running local Kubernetes clusters using Docker-formatted containers as nodes. It is useful for quickly creating ephemeral clusters, and is used as part of the test infrastructure of the Kubernetes project. Running Che in kind is a way to try the application, or for a contributor to test their change quickly with a real cluster.

Prerequisites
Procedure

For Che installation, kind cluster should have an Ingress backend and a persitent volumes storage backend. If these requirements are met, go directly to deploying Che.

Following instruction is a way of configuring Kind cluster to have all needed for Eclipse Che components:

  1. Install csi-driver-host-path in the kind cluster:

    Install snapshotter CRDs as described in the docs:

    $ SNAPSHOTTER_VERSION=v2.1.1
    
    # Apply VolumeSnapshot CRDs
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
    
    # Create snapshot controller
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/${SNAPSHOTTER_VERSION}/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml

    Value of the latest SNAPSHOTTER_VERSION could be found on corresponding release page.

    Then deploy:

    $ git clone https://github.com/kubernetes-csi/csi-driver-host-path && cd csi-driver-host-path
    $ ./deploy/kubernetes-<version>/deploy.sh
    $ kubectl apply -f examples/csi-storageclass.yaml

    Kubernetes version could be obtained via kubectl version command (see Server Version).

  2. Set csi-hostpath-sc as the default StorageClass:

    $ kubectl patch storageclass csi-hostpath-sc -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'
    $ kubectl patch storageclass standard -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}'
  3. Install the NGINX Ingress Controller:

    $ VERSION=0.30.0
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-${VERSION}/deploy/static/mandatory.yaml
    $ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/nginx-${VERSION}/deploy/static/provider/cloud-generic.yaml
  4. Install the MetalLB load balancer:

    $ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/namespace.yaml
    $ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.9.3/manifests/metallb.yaml
    $ kubectl create secret generic -n metallb-system memberlist --from-literal=secretkey="$(openssl rand -base64 128)"

    The above command may apply to an out-of-date version of MetalLB Kubernetes manifests. See the installation instructions for the most up-to-date command.

  5. Determine an IP range to allocate to MetalLB from the docker bridge network:

    $ docker inspect bridge | grep -C 5 Subnet
    "IPAM": {
                "Driver": "default",
                "Options": null,
                "Config": [
                    {
                        "Subnet": "172.17.0.0/16",
                        "Gateway": "172.17.0.1"
                    }
                ]
            },
            "Internal": false,

    In this case, there is a /16 subnet range to allocate. Choose a section in the 172.17.250.0 range.

  6. Create a ConfigMap for MetalLB specifying the IP range to expose:

    $ cat << EOF > metallb-config.yaml
    apiVersion: v1
    kind: ConfigMap
    metadata:
      namespace: metallb-system
      name: config
    data:
      config: |
        address-pools:
        - name: default
          protocol: layer2
          addresses:
          - 172.17.250.1-172.17.250.250
    EOF
    $ kubectl apply -f metallb-config.yaml
  7. The ingress-nginx service now has an external IP:

    $ kubectl get svc -n ingress-nginx
    NAME            TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                      AGE
    ingress-nginx   LoadBalancer   10.107.194.26   172.17.250.1   80:32033/TCP,443:30428/TCP   19h
  1. Run chectl, using the external IP of the ingress-nginx Service as an nip.io URL:

    $ chectl server:start --installer operator --platform k8s --domain 172.17.250.1.nip.io

    In some cases, after all the steps above, it is still not possible to reach Che from the host machine. If you encounter such problem, refer to kind cluster documentation or forums on how to make an endpoint available outside the kind cluster for your system and network configuration.

Importing certificates to browsers

This section describes how to import a root certificate authority into a web browser to use Che with self-signed TLS certificates.

When a TLS certificate is not trusted, the error message Authorization token is missing. Click here to reload page blocks the login process. To prevent this, add the public part of the self-signed CA certificate into the browser after installing Che.

Adding certificates to Google Chrome on Linux or Windows

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the warning or open lock icon on the left of the address bar.

    2. Click Certificates and navigate to the Details tab.

    3. Select the top-level certificate which is the Root certificate authority and export it:

      • On Linux, click the Export button.

      • On Windows, click the Save to file button.

  3. Go to Google Chrome Settings, then to the Authorities tab

  4. In the left panel, select Advanced and continue to Privacy and security.

  5. At the center of the screen, click Manage certificates and navigate to Authorities tab.

  6. Click the Import button and open the saved certificate file.

  7. Select Trust this certificate for identifying websites and click the OK button.

  8. After adding the Che certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.

Adding certificates to Google Chrome and Safari on macOS

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.

    2. Click Certificates.

    3. Select the certificate to use and drag and drop its displayed large icon to the desktop.

  3. Open the Keychain Access application.

  4. Select the System keychain and drag and drop the saved certificate file to it.

  5. Double-click the imported CA, then go to Trust and select When using this certificate: Always Trust.

  6. Restart the browser for the added certificated to take effect.

Adding certificates to Firefox

Procedure
  1. Navigate to URL where Che is deployed.

  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.

    2. Click the > button next to the Connection not secure warning.

    3. Click the More information button.

    4. Click the View Certificate button on the Security tab.

    5. Select the second certificate tab. The certificate Common Name should start with ingress-operator

    6. Click the PEM (cert) link and save the certificate.

  3. Navigate to about:preferences, search for certificates, and click View Certificates.

  4. Go to the Authorities tab, click the Import button, and open the saved certificate file.

  5. Check Trust this CA to identify websites and click OK.

  6. Restart Firefox for the added certificated to take effect.

  7. After adding the Che certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.