This section describes the building of registries and updating a running Che server to point to the registries.

Building a custom devfile registry

This section describes how to build a custom devfiles registry. Following operations are covered:

  • Getting a copy of the source code necessary to build a devfiles registry.

  • Adding a new devfile.

  • Building the devfiles registry.

Procedure

  1. Clone the devfile registry repository:

    $ git clone git@github.com:eclipse/che-devfile-registry.git
$ cd che-devfile-registry

  2. In the ./che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.

    File organization for a devfile
    ./che-devfile-registry/devfiles/
└── <devfile-name>
    ├── devfile.yaml
    └── meta.yaml

  3. Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see the Making a workspace portable using a Devfile section.

  4. Ensure that the meta.yaml file conforms to the following structure:

    Table 1. Parameters for a devfile meta.yaml
    Attribute Description

    description

    Description as it appears on the user dashboard.

    displayName

    Name as it appears on the user dashboard.

    globalMemoryLimit

    The sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the Che server.

    icon

    Link to an .svg file that is displayed on the user dashboard.

    tags

    List of tags. Tags usually include the tools included in the stack.
    Example devfile meta.yaml
    displayName: Rust
description: Rust Stack with Rust 1.39
tags: ["Rust"]
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
globalMemoryLimit: 1686Mi

  5. Build the containers for the custom devfile registry:

    $ docker build -t my-devfile-registry .

Building a custom plug-in registry

This section describes how to build a custom plug-in registry. Following operations are covered:

  • Getting a copy of the source code necessary to build a custom plug-in registry.

  • Adding a new plug-in.

  • Building the custom plug-in registry.

Procedure

  1. Clone the plug-in registry repository:

    $ git clone git@github.com:eclipse/che-plugin-registry.git
$ cd che-plugin-registry

  2. In the ./che-plugin-registry/v3/plugins/ directory, create new directories <publisher>/<plugin-name>/<plugin-version>/ and a meta.yaml file in the last directory.

    File organization for a plugin
    ./che-plugin-registry/v3/plugins/
├── <publisher>
│   └── <plugin-name>
│       ├── <plugin-version>
│       │   └── meta.yaml
│       └── latest.txt

  3. Add valid content to the meta.yaml file. See the “Using a Visual Studio Code extension in Che” section or the README.md file in the eclipse/che-plugin-registry repository for a detailed description of the meta.yaml file format.

  4. Create a file named latest.txt with content the name of the latest <plugin-version> directory.

    Example
    $ tree che-plugin-registry/v3/plugins/redhat/java/
che-plugin-registry/v3/plugins/redhat/java/
├── 0.38.0
│   └── meta.yaml
├── 0.43.0
│   └── meta.yaml
├── 0.45.0
│   └── meta.yaml
├── 0.46.0
│   └── meta.yaml
├── 0.50.0
│   └── meta.yaml
└── latest.txt
$ cat che-plugin-registry/v3/plugins/redhat/java/latest.txt
0.50.0

  5. Build the containers for the custom plug-in registry:

    $ docker build -t my-devfile-registry .

Deploying the 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 and 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 (or, the eval $\{minishift docker-env} command for Minishift).

Otherwise, these images can be pushed to a container registry (public, such as quay.io, or the DockerHub, or 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="IfNotPresent" \
 ./kubernetes/che-plugin-registry/
    1 If installed using chectl, the default Che namespace is default. 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="IfNotPresent" \
 ./deploy/kubernetes/che-devfile-registry/
    1 If installed using chectl, the default Che namespace is default. 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 app=che-plugin-registry (or app=che-plugin-registry for the devfile registry).

    $ kubectl get -o custom-columns=TYPE:.kind,NAME:.metadata.name \
  -l app=che-plugin-registry pod,svc,ingress
TYPE      NAME
Pod       che-plugin-registry-5c7cd8d5c9-zlqlz
Service   che-plugin-registry
Ingress   che-plugin-registry

  4. Check if the registries are deployed successfully on Kubernetes.

    1. To verify that the new plug-in is correctly published to the plug-in registry, make a request to the registry path /v3/plugins/index.json (or /devfiles/index.json for the devfile registry).

      $ URL=$(kubectl get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry ingress --no-headers)
$ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
$ echo ${INDEX_JSON} | grep -A 4 -B 5 "\"name\":\"my-plug-in\""
,\{
 "id": "my-org/my-plug-in/1.0.0",
 "displayName":"This is my first plug-in for Che",
 "version":"1.0.0",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugins shows that we are able to add plugins to the registry...",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/1.0.0" }
}
--
--
,\{
 "id": "my-org/my-plug-in/latest",
 "displayName":"This is my first plug-in for Che",
 "version":"latest",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugins shows that we are able to add plugins to the registry...",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/latest" }
}

    2. Verify that the Che server points to the URL of the registry. To do this, compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap (or CHE_WORKSPACE_DEVFILE__REGISTRY__URL for the devfile registry):

      $ kubectl get \
  -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGINREGISTRYURL']" \
  --no-headers cm/che
URL
http://che-plugin-registry-che.192.168.99.100.nip.io/v3

      with the URL of the Ingress:

      $ kubectl get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry ingress --no-headers
che-plugin-registry-che.192.168.99.100.nip.io

    3. If they 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

      When the new registries are deployed and the Che server is configured to use them, the new plug-ins are available in the Plugin view of a workspace.

      che deploying plugin registry in kubernetes

      The new stacks are displayed in the New Workspace tab of the user dashboard.

      deploying devfile registry in kubernetes

Deploying registries in OpenShift

Procedure

An OpenShift template to deploy the plug-in registry is available in the 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="IfNotPresent"
    1 If installed using chectl, the default Che namespace is default. 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="IfNotPresent"
    1 If installed using chectl, the default Che namespace is default. The OperatorHub installation method deploys Che to the users current namespace.

  3. Check if the registries are deployed successfully on OpenShift.

    1. To verify that the new plug-in is correctly published to the plug-in registry, make a request to the registry path /v3/plugins/index.json (or /devfiles/index.json for the devfile registry).

      $ URL=$(oc get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry route --no-headers)
$ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
$ echo ${INDEX_JSON} | grep -A 4 -B 5 "\"name\":\"my-plug-in\""
,\{
 "id": "my-org/my-plug-in/1.0.0",
 "displayName":"This is my first plug-in for Che",
 "version":"1.0.0",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugin shows that we are able to add plugins to the registry",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/1.0.0" }
}
--
--
,\{
 "id": "my-org/my-plug-in/latest",
 "displayName":"This is my first plug-in for Che",
 "version":"latest",
 "type":"VS Code extension",
 "name":"my-plug-in",
 "description":"This plugin shows that we are able to add plugins to the registry",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plug-in/latest" }
}

    2. Verify that the Che server points to the URL of the registry. To do this, compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap (or CHE_WORKSPACE_DEVFILE__REGISTRY__URL for the devfile registry):

      $ oc get \
  -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGINREGISTRYURL']" \
  --no-headers cm/che
URL
http://che-plugin-registry-che.192.168.99.100.nip.io/v3

      with the URL of the route:

      $ oc get -o 'custom-columns=URL:.spec.rules[0].host' \
  -l app=che-plugin-registry route --no-headers
che-plugin-registry-che.192.168.99.100.nip.io

    3. If they do not match, update the ConfigMap and restart the Che server.

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

When the new registries are deployed and the Che server is configured to use them, the new plug-ins are available in the Plugin view of a workspace and the new stacks are displayed in the New Workspace tab of the user dashboard.

Tags: