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
Deploymentwith aPersistentVolumeClaimfor extension storage. -
A PostgreSQL database
Deploymentwith aPersistentVolumeClaimfor data. -
A one-shot
Jobto provision the database with the required user and access token. -
A
ConfigMapfor listing extensions to publish to the registry. -
Optional: A
CronJobfor periodic auto-update of published extensions from the upstream registry.
When disabled, the Operator removes all managed Open VSX resources.
-
An active
kubectlsession 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
Joband the extension auto-updateCronJobrequire 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.vsixfiles.
-
-
Enable the managed Open VSX registry by patching the
CheClustercustom 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.openVSXURLis set, remove the field from theCheClustercustom 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. -
Optional: Configure the server storage size by setting the
claimSizefield. The default is3Gi.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. -
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>" } } } } } }' -
Optional: Publish extensions to the managed registry by editing the
openvsx-server-extensionsConfigMapin the Che namespace:kubectl edit configmap openvsx-server-extensions \ --namespace eclipse-cheThe
extensions.listkey contains one extension entry per line. The following formats are supported:Table 1. Supported formats for the extensions.listkeyFormat Description namespace.namePublish the latest stable (non-pre-release) version from the upstream registry.
namespace.name@versionPublish a specific version. The upstream registry is not queried for the latest version.
Download and publish a
.vsixfile from the URL.Lines starting with
#are treated as comments and ignored. Empty lines are skipped.Exampleextensions.listkeyapiVersion: 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.vsixThe Operator automatically runs a publishing
Jobwhen theConfigMapcontent changes. -
Optional: Set a target platform fallback for extensions that do not provide a universal
.vsix, such as native extensions likems-python.debugpy. Add thearchitecturekey to the sameConfigMap:ExamplearchitecturekeyapiVersion: 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.debugpyThe publishing
Jobrequests the universal.vsixfirst. When the universal.vsixis not found on the upstream registry, theJobfalls back to the platform-specific.vsixfor the configured architecture. When thearchitecturekey is not set, the extension is skipped and theJoblogs a warning.The
architecturekey accepts the following target platform identifiers:win32-x64,win32-arm64,linux-x64,linux-arm64,linux-armhf,alpine-x64,alpine-arm64,darwin-x64anddarwin-arm64. -
Optional: Enable periodic auto-update of published extensions. When enabled, a
CronJobperiodically checks the upstreamopen-vsx.orgregistry 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.organdopenvsx.eclipsecontent.orgfor the auto-update job to fetch newer extension versions. -
Optional: Customize the auto-update schedule and filters. The following fields are available under
spec.components.openVSXRegistry.extensionAutoUpdate:Table 2. Supported fields for the extensionAutoUpdatekeyField Default Description enablefalseEnables the extension auto-update
CronJob.schedule0 0 * * 0Cron schedule expression for the update job.
vsCodeEngineVersionnot 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.
excludedExtensionsempty
List of extension IDs to skip during auto-update, in
namespace.nameformat. 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>"] } } } } }'
-
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>/openvsxin a browser, where<che_host>is the hostname of your Che instance. You can retrieve the URL from theCheClusterstatus: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
CronJobexists: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 |
-
An active
kubectlsession with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.
-
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.orgThe secret must contain all of the following keys:
Table 3. Required keys for the credentials secret Key Description database-userPostgreSQL username.
database-passwordPostgreSQL password.
database-namePostgreSQL database name.
openvsx-publisher-nameLogin name of the Open VSX publisher account with the
privilegedrole.openvsx-publisher-tokenPersonal access token for the publisher account.
openvsx-admin-nameLogin name of the Open VSX admin account.
openvsx-admin-tokenPersonal access token for the admin account.
-
Reference the secret in the
CheClustercustom resource:kubectl patch checluster eclipse-che \ --namespace eclipse-che \ --type merge \ --patch '{ "spec": { "components": { "openVSXRegistry": { "enable": true, "credentialsSecretName": "<secret_name>" } } } }'
-
Verify that the Open VSX server pod is running:
kubectl get pods --namespace eclipse-che -l app.kubernetes.io/component=openvsx-server -
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_PATandOPENVSX_USER_PAT. -
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.
-
An active
kubectlsession with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl. -
The managed Open VSX registry is enabled and running.
-
Edit the
openvsx-serverConfigMap:kubectl edit configmap openvsx-server \ --namespace eclipse-cheThe
ConfigMapcontains a singleapplication.ymlkey with the Open VSX Spring Boot configuration.
-
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.
-
An active
kubectlsession with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.
-
Set the
enablefield tofalse: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.
-
Optional: To use a registry other than the default for your Che installation, set the
openVSXURLfield: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 openVSXURLfieldValue Selected registry https://open-vsx.orgThe 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-registrypod. 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.
-
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
openVSXURLfield selects the registry you intend to use. An unset field and an empty string select different registries, so read the raw value rather than ajsonpathexpression, 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 openVSXURLfieldOutput Selected registry nullThe default registry for your Che installation.
""The deprecated embedded Open VSX registry instance in the
plugin-registrypod."<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.