Running custom registries

Prerequisites

The my-plug-in-registry and my-devfile-registry images used in this section are built using the docker command. This section assumes that these images are available on the Kubernetes or OpenShift cluster where Che is deployed.

This is true on Minishift or Minikube, for example, if before running the docker build commands, the user executed:

  • The eval ${minikube docker-env} command for Minikube.

  • The eval ${minishift docker-env} command for Minishift.

These images can be then pushed to:

  • A public container registry such as quay.io, or the DockerHub.

  • A private registry.

Deploying registries in Kubernetes

Procedure

A Helm chart for the plug-in registry is available in the /kubernetes/che-plugin-registry/ directory of the GitHub repository.

  1. To deploy the plug-in registry using the Helm chart, run the following command:

    NAMESPACE=<namespace-name>     (1)
    DOMAIN=<kubernetes-cluster-domain> (2)
    IMAGE="my-plug-in-registry"
    helm upgrade --install che-plugin-registry \
     --debug \
     --namespace ${NAMESPACE} \
     --set global.ingressDomain=${DOMAIN} \
     --set chePluginRegistryImage=${IMAGE} \
     --set chePluginRegistryImagePullPolicy="Always" \
     ./kubernetes/che-plugin-registry/
    1 If installed using chectl, the default Che namespace is eclipse-che. The OperatorHub installation method deploys Che to the users current namespace.
    2 On Minikube, use $(minikube ip).nip.io
  2. The devfile registry also has a Helm chart in the deploy/kubernetes/che-devfile-registry/ directory of the GitHub repository. To deploy it, run the command:

    NAMESPACE=<namespace-name>     (1)
    DOMAIN=<kubernetes-cluster-domain> (2)
    IMAGE="my-devfile-registry"
    helm upgrade --install che-devfile-registry \
     --debug \
     --namespace ${NAMESPACE} \
     --set global.ingressDomain=${DOMAIN} \
     --set cheDevfileRegistryImage=${IMAGE} \
     --set cheDevfileRegistryImagePullPolicy="Always" \
     ./deploy/kubernetes/che-devfile-registry/
    1 If installed using chectl, the default Che namespace is eclipse-che. The OperatorHub installation method deploys Che to the users current namespace.
    2 On Minikube, use $(minikube ip).nip.io
  3. The Helm chart creates a Pod, a service, and an Ingress. To get them, use component=plugin-registry (or component=plugin-registry for the devfile registry)

    $ kubectl  get -o custom-columns=TYPE:.kind,NAME:.metadata.name \
      -l component=plugin-registry pod,svc,ingress
    TYPE      NAME
    Pod       che-plugin-registry-5c7cd8d5c9-zlqlz
    Service   che-plugin-registry
    Ingress   che-plugin-registry
Verification steps
  1. The <plug-in> plug-in is available in the plug-in registry.

    Example 1. Find <plug-in> requesting the plug-in registry API.
    $ URL=$(kubectl  get ingress -l app=che,component=plugin-registry \
      -o 'custom-columns=URL:.spec.rules[0].host' --no-headers)
    $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
    $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<plug-in>")'
  2. The <devfile> devfile is available in the devfile registry.

    Example 2. Find <devfile> requesting the devfile registry API.
    $ URL=$(kubectl  get ingress -l app=che,component=devfile-registry \
      -o 'custom-columns=URL:.spec.rules[0].host' --no-headers)
    $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
    $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<devfile>")'
  3. Che server points to the URL of the plug-in registry.

    Example 3. Compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap with the URL of the plug-in registry ingress.
    Get the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap.
    $ kubectl  get cm/che \
      -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \
      --no-headers
    Get the URL of the plug-in registry ingress.
    $ kubectl  get ingress -l app=che,component=plugin-registry \
      -o 'custom-columns=URL: .spec.rules[0].host' --no-headers
  4. Che server points to the URL of the devfile registry.

    Example 4. Compare the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap with the URL of the devfile registry ingress.
    Get the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap.
    $ kubectl  get cm/che \
      -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" \
      --no-headers
    Get the URL of the devfile registry ingress.
    $ kubectl  get ingress -l app=che,component=devfile-registry \
      -o 'custom-columns=URL: .spec.rules[0].host' --no-headers
  5. If the values do not match, update the ConfigMap and restart the Che server.

    $ kubectl  edit cm/che
    (...)
    $ kubectl  scale --replicas=0 deployment/che
    $ kubectl  scale --replicas=1 deployment/che

  • The plug-ins are available in the:

    • Completion to chePlugin components in the Devfile tab of a workspace details

    • Plugin Che-Theia view of a workspace

  • The devfiles are available in the Get Started and Create Custom Workspace tab of the user dashboard.

Deploying registries in OpenShift

Procedure

An OpenShift template to deploy the plug-in registry is available in the deploy/openshift/ directory of the GitHub repository.

  1. To deploy the plug-in registry using the OpenShift template, run the following command:

    NAMESPACE=<namespace-name>  (1)
    IMAGE_NAME="my-plug-in-registry"
    IMAGE_TAG="latest"
    oc new-app -f openshift/che-plugin-registry.yml \
     -n "$\{NAMESPACE}" \
     -p IMAGE="$\{IMAGE_NAME}" \
     -p IMAGE_TAG="$\{IMAGE_TAG}" \
     -p PULL_POLICY="Always"
    1 If installed using chectl, the default Che namespace is eclipse-che. The OperatorHub installation method deploys Che to the users current namespace.
  2. The devfile registry has an OpenShift template in the deploy/openshift/ directory of the GitHub repository. To deploy it, run the command:

    NAMESPACE=<namespace-name>  (1)
    IMAGE_NAME="my-devfile-registry"
    IMAGE_TAG="latest"
    oc new-app -f openshift/che-devfile-registry.yml \
     -n "$\{NAMESPACE}" \
     -p IMAGE="$\{IMAGE_NAME}" \
     -p IMAGE_TAG="$\{IMAGE_TAG}" \
     -p PULL_POLICY="Always"
    1 If installed using chectl, the default Che namespace is eclipse-che. The OperatorHub installation method deploys Che to the users current namespace.
Verification steps
  1. The <plug-in> plug-in is available in the plug-in registry.

    Example 5. Find <plug-in> requesting the plug-in registry API.
    $ URL=$(kubectl  get route -l app=che,component=plugin-registry \
      -o 'custom-columns=URL:.spec.host' --no-headers)
    $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
    $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<plug-in>")'
  2. The <devfile> devfile is available in the devfile registry.

    Example 6. Find <devfile> requesting the devfile registry API.
    $ URL=$(kubectl  get route -l app=che,component=devfile-registry \
      -o 'custom-columns=URL:.spec.host' --no-headers)
    $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
    $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<devfile>")'
  3. Che server points to the URL of the plug-in registry.

    Example 7. Compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap with the URL of the plug-in registry route.
    Get the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap.
    $ kubectl  get cm/che \
      -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \
      --no-headers
    Get the URL of the plug-in registry route.
    $ kubectl  get route -l app=che,component=plugin-registry \
      -o 'custom-columns=URL: .spec.host' --no-headers
  4. Che server points to the URL of the devfile registry.

    Example 8. Compare the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap with the URL of the devfile registry route.
    Get the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap.
    $ kubectl  get cm/che \
      -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" \
      --no-headers
    Get the URL of the devfile registry route.
    $ kubectl  get route -l app=che,component=devfile-registry \
      -o 'custom-columns=URL: .spec.host' --no-headers
  5. If the values do not match, update the ConfigMap and restart the Che server.

    $ kubectl  edit cm/che
    (...)
    $ kubectl  scale --replicas=0 deployment/che
    $ kubectl  scale --replicas=1 deployment/che

  • The plug-ins are available in the:

    • Completion to chePlugin components in the Devfile tab of a workspace details

    • Plugin Che-Theia view of a workspace

  • The devfiles are available in the Get Started and Create Custom Workspace tab of the user dashboard.

Adding a custom plug-in registry in an existing Che workspace

The following section describes two methods of adding a custom plug-in registry in an existing Che workspace:

Adding a custom plug-in registry using Command Palette

Prerequisites
  • An instance of Che

Procedure
  1. In the Che IDE, press F1 to open the Command Palette, or navigate to View → Find Command in the top menu.

    The command palette can be also activated by pressing Ctrl+Shift+p (or Cmd+Shift+p on macOS).

  2. Enter the Add Registry command into the search box and pres Enter once filled.

  3. Enter the registry name and registry URL in next two command prompts.

    • After adding a new plug-in registry, the list of plug-ins in the Plug-ins view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message.

Adding a custom plug-in registry using the settings.json file

The following section describes the use of the main Che Settings menu to edit and add a new plug-in registry using the settings.json file.

Prerequisites
  • An instance of Che

Procedure
  1. From the main Che screen, select Open Preferences by pressing Ctrl+, or using the gear wheel icon on the left bar.

  2. Select Che Plug-ins and continue by Edit in setting.json link.

    The setting.json file is displayed.

  3. Add a new plug-in registry using the chePlugins.repositories attribute as shown below:

    {
    “application.confirmExit”: “never”,
    “chePlugins.repositories”: {“test”: “https://test.com”}
    }
  4. Save the changes to add a custom plug-in registry in an existing Che workspace.

    • A newly added plug-in validation tool checks the correctness of URL values set in the chePlugins.repositories field of the settings.json file.

    • After adding a new plug-in registry, the list of plug-ins in the Plug-ins view is refreshed, and if the new plug-in registry is not valid, a user is notified by a warning message. This check is also functional for plug-ins added using the Command palette command Add plugin registry.