From 7e05aef8dbdf74dd033fafeef6315881366987e8 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Mon, 8 Jun 2026 13:34:26 +0000 Subject: [PATCH] procedures: Add documentation for operator-managed OpenVSX registry Document the new CheCluster-managed OpenVSX deployment feature introduced in che-operator PR #2130. This adds a new procedure article explaining how to enable and configure the operator-managed OpenVSX registry with PostgreSQL persistence. The managed registry approach differs from existing manual deployment procedures by providing a fully automated, operator-managed OpenVSX instance that is deployed, configured, and maintained as a Che operand. Co-Authored-By: Claude Sonnet 4.5 Signed-off-by: Anatolii Bazko --- modules/administration-guide/nav.adoc | 1 + ...nabling-the-managed-open-vsx-registry.adoc | 167 ++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 modules/administration-guide/pages/enabling-the-managed-open-vsx-registry.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index e26825866c..55ff0e31fd 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -118,6 +118,7 @@ * xref:managing-ide-extensions.adoc[] ** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[] ** xref:configuring-the-open-vsx-registry-url.adoc[] +** xref:enabling-the-managed-open-vsx-registry.adoc[] ** xref:proc_deploy-open-vsx-from-source.adoc[] ** xref:proc_deploy-open-vsx-from-workspace.adoc[] ** xref:proc_configure-internal-open-vsx-access.adoc[] diff --git a/modules/administration-guide/pages/enabling-the-managed-open-vsx-registry.adoc b/modules/administration-guide/pages/enabling-the-managed-open-vsx-registry.adoc new file mode 100644 index 0000000000..3c5eb522a1 --- /dev/null +++ b/modules/administration-guide/pages/enabling-the-managed-open-vsx-registry.adoc @@ -0,0 +1,167 @@ +:_content-type: PROCEDURE +:description: Enable the {prod} operator to deploy and manage a dedicated Open VSX registry instance with PostgreSQL +:keywords: administration guide, openvsx, registry, extensions, operand, managed +:navtitle: Enable the managed Open VSX registry +:page-aliases: + +[id="enabling-the-managed-open-vsx-registry"] += Enable the managed Open VSX registry + +[role="_abstract"] +Enable {prod-short} to automatically deploy and manage a dedicated Open VSX registry instance with PostgreSQL persistence. The managed registry runs as a {prod-short} operand, providing a self-contained, operator-managed extension registry that requires no manual deployment or maintenance. + +When enabled, the {prod-short} operator creates and manages: + +* **OpenVSX server** — A Spring Boot application serving the extension registry API and web interface +* **PostgreSQL database** — Persistent storage for extension metadata and user accounts +* **Persistent volumes** — Storage for extension files and database data +* **Ingress** — Public or internal route for accessing the registry +* **Database seeding** — Automatic creation of privileged user accounts and personal access tokens +* **Extension publishing** — Optional job to pre-populate extensions from a ConfigMap + +The managed registry is deployed in the same namespace as {prod-short} and shares the same lifecycle. When disabled, all resources are automatically cleaned up. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Enable the managed Open VSX registry by setting `spec.components.openVSX.enable` to `true`: ++ +[source,shell,subs="+quotes,+attributes,+macros"] +---- +{orch-cli} patch checluster {prod-checluster} \ + --namespace {prod-namespace} \ + --type merge \ + --patch '{"spec":{"components":{"openVSX":{"enable":true}}}}' +---- + +. Wait for the {prod-short} operator to create the OpenVSX resources: ++ +[source,shell,subs="+quotes,+attributes"] +---- +{orch-cli} get pods -n {prod-namespace} -l app.kubernetes.io/component=openvsx-server +{orch-cli} get pods -n {prod-namespace} -l app.kubernetes.io/component=openvsx-postgres +---- + +. Retrieve the OpenVSX registry URL from the `CheCluster` status: ++ +[source,shell,subs="+quotes,+attributes"] +---- +{orch-cli} get checluster {prod-checluster} \ + -n {prod-namespace} \ + -o jsonpath='{.status.openVSXURL}' +---- + +.Verification + +* Access the OpenVSX registry URL in a web browser to verify the registry interface is available. +* Start a {prod-short} workspace and verify that the Microsoft Visual Studio Code - Open Source editor can browse and install extensions from the managed registry. + +.Additional configuration + +*Customize storage capacity* + +Configure the persistent volume sizes for the OpenVSX server and PostgreSQL database: + +[source,shell,subs="+quotes,+attributes,+macros"] +---- +{orch-cli} patch checluster {prod-checluster} \ + --namespace {prod-namespace} \ + --type merge \ + --patch '{ + "spec": { + "components": { + "openVSX": { + "server": { + "claimSize": "____" + }, + "postgres": { + "claimSize": "____" + } + } + } + } + }' +---- ++ +where: ++ +`____`:: Storage capacity for extension files. Default: `3Gi`. +`____`:: Storage capacity for PostgreSQL data. Default: `1Gi`. + +NOTE: Most storage classes only support volume expansion, not shrinking. Ensure the specified size is equal to or greater than the current size. + +*Pre-populate extensions* + +Publish extensions to the managed registry by editing the `openvsx-extensions` ConfigMap: + +[source,shell,subs="+quotes,+attributes"] +---- +{orch-cli} edit configmap openvsx-extensions -n {prod-namespace} +---- + +Add extension identifiers in the format `publisher.extension` (one per line) to the ConfigMap data. The {prod-short} operator automatically creates a job to publish the specified extensions. + +// TODO: Verify the exact ConfigMap structure and field name for extension list + +*Customize OpenVSX server configuration* + +Edit the `openvsx-server-config` ConfigMap to modify the Spring Boot application configuration: + +[source,shell,subs="+quotes,+attributes"] +---- +{orch-cli} edit configmap openvsx-server-config -n {prod-namespace} +---- + +The {prod-short} operator automatically restarts the OpenVSX server pod when the ConfigMap is modified. + +// TODO: Document which application.yml properties are safe to modify + +*Configure deployment overrides* + +Override the default resource requests, limits, and other deployment settings: + +[source,shell,subs="+quotes,+attributes,+macros"] +---- +{orch-cli} patch checluster {prod-checluster} \ + --namespace {prod-namespace} \ + --type merge \ + --patch '{ + "spec": { + "components": { + "openVSX": { + "server": { + "deployment": { + "containers": [{ + "name": "openvsx-server", + "resources": { + "requests": { + "memory": "____", + "cpu": "____" + }, + "limits": { + "memory": "____", + "cpu": "____" + } + } + }] + } + } + } + } + } + }' +---- ++ +Default resource allocations: ++ +* OpenVSX server: 512Mi request, 2Gi limit (memory); 100m request, 1 limit (CPU) +* PostgreSQL: 256Mi request, 1024Mi limit (memory); 100m request, 1 limit (CPU) + +[role="_additional-resources"] +.Additional resources + +* xref:managing-ide-extensions.adoc[] +* xref:configuring-the-open-vsx-registry-url.adoc[]