OpenShift Console Demo Plugin

This project emulates a standalone repository hosting a sample dynamic plugin for OpenShift Console.

It is meant to serve as a reference for Console plugin developers and for testing dynamic plugin capabilities via end-to-end tests.

Local development

1. yarn build to build the plugin, generating output to dist directory
2. yarn http-server to start an HTTP server hosting the generated assets

Starting up http-server, serving ./dist
Available on:
  http://127.0.0.1:9001
  http://192.168.1.190:9001
  http://10.40.192.80:9001
Hit CTRL-C to stop the server

The server runs on port 9001 with caching disabled and CORS enabled. Additional server options can be passed to the script, for example:

yarn http-server -a 127.0.0.1

See the plugin development section in Console Dynamic Plugins README for details on how to run Bridge using local plugins.

Deployment on cluster

Console dynamic plugins are supposed to be deployed via OLM operators. In case of demo plugin, we just apply a minimal OpenShift manifest which adds the necessary resources.

oc apply -f oc-manifest.yaml

Note that the Service exposing the HTTP server is annotated to have a signed service serving certificate generated and mounted into the image. This allows us to run the server with HTTP/TLS enabled, using a trusted CA certificate.

Enabling the plugin

Once deployed on the cluster, demo plugin must be enabled before it can be loaded by Console.

To enable the plugin manually, edit Console operator config and make sure the plugin's name is listed in the spec.plugins sequence (add one if missing):

oc edit console.operator.openshift.io cluster

# ...
spec:
  plugins:
    - node-health-checks
# ...

Proxy service

In case the plugin needs to communicate with some in-cluster service, it can declare a service proxy in its ConsolePlugin resource using the spec.proxy array field. Each entry needs to specify type and alias of the proxy, under the type and alias field. For the Service proxy type, a service field with name, namespace and port needs to be specified.

Console backend exposes following endpoint in order to proxy the communication between plugin and the service: /api/proxy/plugin/<plugin-name>/<proxy-alias>/<request-path>?<optional-query-parameters>

An example proxy request path from helm plugin with a helm-charts service to list ten helm releases: /api/proxy/plugin/helm/helm-charts/releases?limit=10

Proxied request will use service CA bundle by default. The service must use HTTPS. If the service uses a custom service CA, the caCertificate field must contain the certificate bundle. In case the service proxy request needs to contain logged-in user's OpenShift access token, the authorize field needs to be set to true. The user's OpenShift access token will be then passed in the HTTP Authorization request header, for example:

Authorization: Bearer sha256~kV46hPnEYhCWFnB85r5NrprAxggzgb6GOeLbgcKNsH0

# ...
spec:
  proxy:
  - type: Service
    alias: helm-charts
    authorize: true
    caCertificate: '-----BEGIN CERTIFICATE-----\nMIID....'
    service:
      name: helm-charts
      namespace: helm
      port: 8443
# ...

Local development

In case of local developement of the dynamic plugin, just set up your HTTP server locally and pass its endpoint address in form of a service proxy entry to the console server in form of JSON, using the --plugin-proxy flag.

Example:

 ./bin/bridge --plugin-proxy='{"services":[{"consoleAPIPath":"/api/proxy/namespace/serviceNamespace/service/serviceName:9991/","endpoint":"http://localhost:8080"}]}'

The service proxy entry besides service endpoint contain also consoleAPIPath, so the console server knows which path is should expose and proxy to service endpoint. Note that the service endpoint needs to contain scheme and consoleAPIPath needs to contain trailing slash in order for request to be proxied correctly.

Docker image

Following commands should be executed in Console repository root.

1. Build the image:

   docker build -f Dockerfile.plugins.demo -t quay.io/$USER/console-demo-plugin .

2. Run the image:

   docker run -it -p 9001:9001 quay.io/$USER/console-demo-plugin

3. Push the image to image registry:

   docker push quay.io/$USER/console-demo-plugin

Update and apply oc-manifest.yaml to use a custom plugin image.

i18n

The demo plugin demonstrates how you can translate messages in a dynamic plugin with react-i18next. The i18n namespace must match the name of the ConsolePlugin resource with the plugin__ prefix to avoid naming conflicts. For example, the demo plugin uses the plugin__console-demo-plugin namespace. You can use the useTranslation hook with this namespace as follows:

conster Header: React.FC = () => {
  const { t } = useTranslation('plugin__console-demo-plugin');
  return <h1>{t('Hello, World!')}</h1>;
};

For labels in console-extensions.json, you can use the format %plugin__console-demo-plugin~My Label%. Console will replace the value with the message for the current language from the plugin__console-demo-plugin namespace. For example:

  {
    "type": "console.navigation/section",
    "properties": {
      "id": "admin-demo-section",
      "perspective": "admin",
      "name": "%plugin__console-demo-plugin~Demo Plugin%"
    }
  }

Note that you will need to include a comment in a TypeScript file like the following for i18next-parser to add the message from console-extensions.json to your message catalog.

// t('plugin__console-demo-plugin~Demo Plugin')

Running yarn i18n updates the JSON files in the locales folder of the dynamic plugin when adding or changing messages.