Enable the managed Open VSX registry

Enable the managed Open VSX registry if it was disabled or if you upgraded from a release where it was not the default. Che deploys and manages a dedicated Open VSX server with a PostgreSQL database as Operator-managed components.

The managed registry is exposed through the Che gateway and provides a private, curated extension registry without requiring manual deployment or database administration.

To use a public or standalone registry instead, set spec.components.pluginRegistry.openVSXURL to its URL. See Use an alternative extension registry.

When enabled, the Che Operator creates the following resources:

  • An Open VSX server Deployment with a PersistentVolumeClaim for extension storage.

  • A PostgreSQL database Deployment with a PersistentVolumeClaim for data.

  • A one-shot Job to provision the database with the required user and access token.

  • A ConfigMap for listing extensions to publish to the registry.

  • Optional: A CronJob for periodic auto-update of published extensions from the upstream registry.

When disabled, the Operator removes all managed Open VSX resources.

Prerequisites
  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

  • Outbound HTTPS access from the cluster to the upstream registry is available. Both the publishing Job and the extension auto-update CronJob require it.

    If your cluster restricts egress traffic, add the following hosts to the allowlist:

    • open-vsx.org: serves the registry API that the jobs query for extension metadata and versions.

    • openvsx.eclipsecontent.org: the content delivery network that serves the .vsix files.

Procedure
  1. Enable the managed Open VSX registry by patching the CheCluster custom resource:

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "enable": true
            }
          }
        }
      }'

    The Operator deploys the Open VSX server and PostgreSQL database, provisions the database, and exposes the registry through the Che gateway.

    If spec.components.pluginRegistry.openVSXURL is set, remove the field from the CheCluster custom resource to select the managed registry.

    The managed registry starts empty with no pre-installed extensions. You must publish extensions to the registry after enabling it.
  2. Optional: Configure the server storage size by setting the claimSize field. The default is 3Gi.

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "server": {
                "pvc": {
                  "claimSize": "<size>"
                }
              }
            }
          }
        }
      }'

    where <size> is the required storage size. For example: 5Gi.

  3. Optional: Configure the database storage size. The default is 1Gi.

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "database": {
                "pvc": {
                  "claimSize": "<size>"
                }
              }
            }
          }
        }
      }'
  4. Optional: Publish extensions to the managed registry by editing the openvsx-server-extensions ConfigMap in the Che namespace:

    kubectl edit configmap openvsx-server-extensions \
      --namespace eclipse-che

    The extensions.list key contains one extension entry per line. The following formats are supported:

    Table 1. Supported formats for the extensions.list key
    Format Description

    namespace.name

    Publish the latest stable (non-pre-release) version from the upstream registry.

    namespace.name@version

    Publish a specific version. The upstream registry is not queried for the latest version.

    https://…​vsix

    Download and publish a .vsix file from the URL.

    Lines starting with # are treated as comments and ignored. Empty lines are skipped.

    Example extensions.list key
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: openvsx-server-extensions
      namespace: eclipse-che
    data:
      extensions.list: |
        # Publish the latest stable version
        redhat.vscode-yaml
        ms-python.python
        golang.Go
    
        # Pin to a specific version
        redhat.java@1.34.0
    
        # Publish directly from a .vsix URL
        https://open-vsx.org/api/redhat/vscode-xml/0.27.2024120609/file/redhat.vscode-xml-0.27.2024120609.vsix

    The Operator automatically runs a publishing Job when the ConfigMap content changes.

  5. Optional: Set a target platform fallback for extensions that do not provide a universal .vsix, such as native extensions like ms-python.debugpy. Add the architecture key to the same ConfigMap:

    Example architecture key
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: openvsx-server-extensions
      namespace: eclipse-che
    data:
      architecture: "linux-x64"
      extensions.list: |
        # Native extension: no universal .vsix, falls back to linux-x64
        ms-python.debugpy

    The publishing Job requests the universal .vsix first. When the universal .vsix is not found on the upstream registry, the Job falls back to the platform-specific .vsix for the configured architecture. When the architecture key is not set, the extension is skipped and the Job logs a warning.

    The architecture key accepts the following target platform identifiers: win32-x64, win32-arm64, linux-x64, linux-arm64, linux-armhf, alpine-x64, alpine-arm64, darwin-x64 and darwin-arm64.

  6. Optional: Enable periodic auto-update of published extensions. When enabled, a CronJob periodically checks the upstream open-vsx.org registry for newer versions of extensions published in the managed registry and re-publishes them automatically.

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "extensionAutoUpdate": {
                "enable": true
              }
            }
          }
        }
      }'

    By default, the auto-update job runs weekly on Sunday at midnight (schedule: 0 0 * * 0).

    The cluster must have outbound HTTPS access to open-vsx.org and openvsx.eclipsecontent.org for the auto-update job to fetch newer extension versions.

  7. Optional: Customize the auto-update schedule and filters. The following fields are available under spec.components.openVSXRegistry.extensionAutoUpdate:

    Table 2. Supported fields for the extensionAutoUpdate key
    Field Default Description

    enable

    false

    Enables the extension auto-update CronJob.

    schedule

    0 0 * * 0

    Cron schedule expression for the update job.

    vsCodeEngineVersion

    not set

    When set, only extensions compatible with this Visual Studio Code engine version are updated. When omitted, the latest non-pre-release version of each extension is used regardless of engine compatibility.

    excludedExtensions

    empty

    List of extension IDs to skip during auto-update, in namespace.name format. For example: redhat.java, redhat.vscode-xml.

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "extensionAutoUpdate": {
                "enable": true,
                "schedule": "<cron_expression>",
                "vsCodeEngineVersion": "<version>",
                "excludedExtensions": ["<namespace.name>"]
              }
            }
          }
        }
      }'
Verification
  • Verify that the Open VSX server and database pods are running:

    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server
    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-database
  • Access the Open VSX registry UI by navigating to https://<che_host>/openvsx in a browser, where <che_host> is the hostname of your Che instance. You can retrieve the URL from the CheCluster status:

    kubectl get checluster eclipse-che \
      --namespace eclipse-che \
      -o jsonpath='{.status.openVSXURL}'
  • Open a workspace and verify that extensions from the managed registry are available in the Extensions view.

  • If extension auto-update is enabled, verify that the CronJob exists:

    kubectl get cronjob --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server-extensions-update

Configure custom credentials for the managed Open VSX registry

By default, the Operator generates an openvsx-credentials secret with random passwords and access tokens. To use custom database credentials and Open VSX user accounts, create a secret and reference it in the CheCluster custom resource.

The secret must exist before it is referenced in the CheCluster custom resource. The Operator validates the secret on create and update and rejects the change if the secret is missing or incomplete.

Prerequisites
  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

Procedure
  1. Create a secret with the required credentials:

    kubectl create secret generic <secret_name> \
      --namespace eclipse-che \
      --from-literal=database-user=<db_user> \
      --from-literal=database-password=<db_password> \
      --from-literal=database-name=<db_name> \
      --from-literal=openvsx-publisher-name=<publisher_name> \
      --from-literal=openvsx-publisher-token=<publisher_token> \
      --from-literal=openvsx-admin-name=<admin_name> \
      --from-literal=openvsx-admin-token=<admin_token>
    kubectl label secret <secret_name> \
      --namespace eclipse-che \
      app.kubernetes.io/part-of=che.eclipse.org

    The secret must contain all of the following keys:

    Table 3. Required keys for the credentials secret
    Key Description

    database-user

    PostgreSQL username.

    database-password

    PostgreSQL password.

    database-name

    PostgreSQL database name.

    openvsx-publisher-name

    Login name of the Open VSX publisher account with the privileged role.

    openvsx-publisher-token

    Personal access token for the publisher account.

    openvsx-admin-name

    Login name of the Open VSX admin account.

    openvsx-admin-token

    Personal access token for the admin account.

  2. Reference the secret in the CheCluster custom resource:

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "enable": true,
              "credentialsSecretName": "<secret_name>"
            }
          }
        }
      }'
Verification
  1. Verify that the Open VSX server pod is running:

    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server
  2. Verify that the custom credentials are injected as environment variables in the Open VSX server pod:

    kubectl exec deploy/openvsx-server \
      --namespace eclipse-che -- \
      env | grep -E 'OPENVSX_ADMIN_PAT|OPENVSX_USER_PAT'

    The output should include OPENVSX_ADMIN_PAT and OPENVSX_USER_PAT.

  3. Verify that the database pod uses the custom credentials:

    kubectl exec deploy/openvsx-database \
      --namespace eclipse-che -- \
      env | grep -E 'POSTGRESQL_'

Customize the Open VSX server configuration

The Operator creates an openvsx-server ConfigMap with a default application.yml configuration when the managed registry is first enabled. This ConfigMap is user-editable: the Operator creates it once and does not overwrite subsequent changes. Modifying the ConfigMap automatically triggers a rolling restart of the Open VSX server pod.

Prerequisites
  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

  • The managed Open VSX registry is enabled and running.

Procedure
  1. Edit the openvsx-server ConfigMap:

    kubectl edit configmap openvsx-server \
      --namespace eclipse-che

    The ConfigMap contains a single application.yml key with the Open VSX Spring Boot configuration.

Verification
  • Verify that the Open VSX server pod has restarted with the updated configuration:

    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server

Delete extensions from the managed Open VSX registry

To remove an extension, one of its versions, or one of its target platforms from a running managed registry, see Delete extensions from the managed Open VSX registry.

Disable the managed Open VSX registry

Disable the managed Open VSX registry to remove the Open VSX server, PostgreSQL database, and all associated resources from the namespace, and optionally select the registry that workspaces use instead.

Disabling the operand does not by itself change which registry workspaces use. When spec.components.pluginRegistry.openVSXURL is set, workspaces use that value whether or not the managed registry is enabled. When the field is not set, workspaces use the managed registry while it is enabled, and the default registry for your Che installation after you disable it. The Operator defines this default, which differs between installations.

Prerequisites
  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

Procedure
  1. Set the enable field to false:

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "openVSXRegistry": {
              "enable": false
            }
          }
        }
      }'

    The Operator removes all managed Open VSX resources, including deployments, services, persistent volume claims, and secrets.

  2. Optional: To use a registry other than the default for your Che installation, set the openVSXURL field:

    kubectl patch checluster eclipse-che \
      --namespace eclipse-che \
      --type merge \
      --patch '{
        "spec": {
          "components": {
            "pluginRegistry": {
              "openVSXURL": "<url_of_an_open_vsx_registry_instance>"
            }
          }
        }
      }'

    where <url_of_an_open_vsx_registry_instance> is one of the following values:

    Table 4. Supported values for the openVSXURL field
    Value Selected registry

    https://open-vsx.org

    The public Open VSX registry. Requires outbound internet access from workspace pods.

    A standalone instance URL

    A self-hosted Open VSX registry that is accessible from workspace pods. Keep this value set: clearing it selects the deprecated embedded registry instead.

    "" (empty string)

    The deprecated embedded Open VSX registry instance in the plugin-registry pod. Set the empty string only when you intend to use the embedded registry.

    Not set

    The default registry for your Che installation. Omitting the field is not the same as setting an empty string: an empty string selects the embedded registry.

    For more information, see Use an alternative extension registry.

Verification
  • Verify that no Open VSX pods remain in the namespace:

    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server
    kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-database
  • Verify that the openVSXURL field selects the registry you intend to use. An unset field and an empty string select different registries, so read the raw value rather than a jsonpath expression, which renders both as empty output:

    kubectl get checluster eclipse-che \
      --namespace eclipse-che \
      -o json | jq '.spec.components.pluginRegistry.openVSXURL'
    Table 5. Expected output for the openVSXURL field
    Output Selected registry

    null

    The default registry for your Che installation.

    ""

    The deprecated embedded Open VSX registry instance in the plugin-registry pod.

    "<url>"

    The standalone Open VSX registry instance at that URL.

  • Open a workspace and verify that extensions from the selected registry are available in the Extensions view.