Building and running a custom registry image

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

Cloning the registries

This section describes how to clone the devfile and plug-in registries.

Cloning the plug-in registry

This section describes how to clone the che-plugin-registry Git repository.

Procedure

Run the following command:

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

Verify the repository has been cloned.

$ tree -L 2 ./che-plugin-registry
./che-plugin-registry
(...)
├── Dockerfile   (1)
├── README.md    (2)
├── kubernetes   (3)
├── openshift    (4)
├── plugins      (5)
├── v2           (6)
└── v3           (7)

1	Dockerfile to build the container image
2	Updated instructions to build and run the registry
3	Kubernetes deployment files
4	OpenShift deployment files
5	Plug-in folder
6	Deprecated plug-in folder that may be removed in the future
7	Deprecated plug-in folder that may be removed in the future

Cloning the devfile registry

This section describes how to clone the che-devfile-registry Git repository.

Procedure

Run the following command:

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

Verify the repository has been cloned.

$ tree -L 2 ./che-devfile-registry
./che-devfile-registry
(...)
├── Dockerfile             (1)
├── README.md              (2)
├── arbitrary-users-patch  (3)
├── deploy
│ ├── kubernetes           (4)
│ └── openshift            (5)
└── devfiles               (6)

1	Dockerfile to build the container image
2	Updated instructions to build and run the registry
3	Scripts to patch images so that they work fine even if run as arbitrary users
4	Kubernetes deployment files
5	OpenShift deployment files
6	Devfiles folder

Modifying the registries

This section explains how to modify the existing content of the devfile and plug-in registries: the devfiles and plug-in metadata.

Prerequisites

The registries are cloned following the Cloning the registries procedure.

Adding a new plug-in

The v3/plugins/ directory in the repository contains the plug-ins. The following is the structure of a plug-in directory:

./che-plugin-registry/v3/plugins
 ├── <publisher>
 ├── <plugin-name>
 ├── <plugin-version>
 └── meta.yaml

To add a new plug-in:

Procedure

In the v3/plugins/ directory, create a new directory and name it <publisher>/<plugin-name>/<plugin-version>/.

Create a plug-in meta.yaml file in the new directory.

Example

The following is an example directory called my-org/my-plugin/1.0.0/, and it contains a meta.yaml file:

$ mkdir -p che-plugin-registry/v3/plugins/my-org/my-plugin/1.0.0/
$ touch che-plugin-registry/v3/plugins/my-org/my-plugin/1.0.0/meta.yaml
$ tree ./che-plugin-registry/v3/plugins
./che-plugin-registry/v3/plugins
 ├── my-org
 ├── my-plugin
 ├── 1.0.0
 └── meta.yaml

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.

Create a directory called latest/ and copy the meta.yaml file in it, too. The meta.yaml file in the latest/ directory is used when the plug-in version is not specified (in a devfile, for example).

The latest/ directory should always contain a copy of the latest stable meta.yaml file.

Example

$ mkdir che-plugin-registry/v3/plugins/my-org/my-plugin/latest/
$ copy che-plugin-registry/v3/plugins/my-org/my-plugin/1.0.0/meta.yaml \
che-plugin-registry/v3/plugins/my-org/my-plugin/latest
$ tree ./che-plugin-registry/v3/plugins
./che-plugin-registry/v3/plugins
 ├── my-org
 ├── my-plugin
 ├── 1.0.0
 ├── meta.yaml
 ├── latest
 └── meta.yaml

Adding a new devfile

The devfiles/ directory contains the devfiles. Every devfile directory has the following structure:

./che-devfile-registry/devfiles
 ├── <stack-name>
 ├── devfile.yaml
 └── meta.yaml

To add a new devfile:

Procedure

In the devfiles/ directory, create a new subdirectory <stack-name>/.

In this new subdirectory, add a new plug-in devfile.yaml file and a meta.yaml file. The following is an example my-stack/ directory, and it contains a devfile.yaml file and a meta.yaml file:

$ mkdir -p che-devfile-registry/devfiles/my-devfile
$ touch che-devfile-registry/devfiles/my-devfile/devfile.yaml
$ touch che-devfile-registry/devfiles/my-devfile/meta.yaml
$ tree ./che-devfile-registry/devfiles
./che-devfile-registry/devfiles
 ├── my-devfile
 ├── devfile.yaml
 └── meta.yaml

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.

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

displayName: My Stack                                        (1)
description: This is a custom stack for Che                  (2)
tags: ["Java", "maven", "ubi"]                               (3)
icon: https://www.eclipse.org/che/images/logo-eclipseche.svg (4)
globalMemoryLimit: 1686Mi                                    (5)

1	Name of the stack as it appears on the user dashboard.
2	Description of the stack as it appears on the user dashboard.
3	Tags of the stack. Tags usually include the tools included in the stack.
4	The link to an `.svg` file that is displayed on the user dashboard.
5	The sum of the memory limits of all the components of the stack. This number will be visible on the user dashboard. It is informative and is not taken into account by the Che server.

Building the images of the registries

The Dockerfiles to build the registries are in the root directory of the respective GitHub repository.

Building the images of the plug-in registry

Procedure

Run the following command

$ docker build -t my-plugin-registry ./che-plugin-registry/

Building the images of the devfile registry

Procedure

Run the following command

$ docker build -t my-devfile-registry ./che-devfile-registry

Deploying the registries

Prerequisites

The my-plugin-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.

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-plugin-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	The default Che namespace is `che`.
2	On Minikube, use `$(minikube ip).nip.io`

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	The default Che namespace is `che`.
2	On Minikube, use `$(minikube ip).nip.io`

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

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-plugin\""
,\{
 "id": "my-org/my-plugin/1.0.0",
 "displayName":"This is my first Che plugin",
 "version":"1.0.0",
 "type":"VS Code extension",
 "name":"my-plugin",
 "description":"This plugins shows that we are able to add plugins to the registry...",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plugin/1.0.0" }
}
--
--
,\{
 "id": "my-org/my-plugin/latest",
 "displayName":"This is my first Che plugin",
 "version":"latest",
 "type":"VS Code extension",
 "name":"my-plugin",
 "description":"This plugins shows that we are able to add plugins to the registry...",
 "publisher":"my-org",
 "links": \{"self":"/v3/plugins/my-org/my-plugin/latest" }
}

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_PLUGIN__REGISTRY__URL']" \
  --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

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.

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

Deploying registries in OpenShift

Procedure

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

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

NAMESPACE=<namespace-name>  (1)
IMAGE_NAME="my-plugin-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	The default Che namespace is `che`.

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	The default Che namespace is `che`.

Check if the registries are deployed successfully on OpenShift. The steps to check are similar to the Kubernetes steps. For details, see the Deploying registries in Kubernetes section. The only difference is that, on OpenShift, Ingresses are replaced with routes.

Tags: