Procedures/managed openvsx registry

modules/administration-guide/nav.adoc

@@ -67,6 +67,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[]

modules/administration-guide/pages/enabling-the-managed-open-vsx-registry.adoc

@@ -0,0 +1,375 @@
+:_content-type: PROCEDURE
+:description: Enable the Operator-managed Open VSX registry to deploy a dedicated Open VSX server and PostgreSQL database as {prod} operands
+:keywords: administration guide, openvsx, registry, extensions, managed, operator
+:navtitle: Enable the managed Open VSX registry
+
+[id="enabling-the-managed-open-vsx-registry"]
+= Enable the managed Open VSX registry
+
+[role="_abstract"]
+[IMPORTANT]
+====
+The managed Open VSX registry is a Technology Preview feature only.
+====
+
+Enable {prod-short} to deploy and manage a dedicated Open VSX server with a PostgreSQL database as Operator-managed components. The managed registry is exposed through the {prod-short} gateway and provides a private, curated extension registry without requiring manual deployment or database administration.
+
+When enabled, the {prod-short} 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.
+
+When disabled, the Operator removes all managed Open VSX resources.
+
+.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 patching the `CheCluster` custom resource:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} patch checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  --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 {prod-short} gateway.
++
+NOTE: 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 `claimSize` field. The default is `3Gi`.
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} patch checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  --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`.
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} patch checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  --type merge \
+  --patch '{
+    "spec": {
+      "components": {
+        "openVSXRegistry": {
+          "database": {
+            "pvc": {
+              "claimSize": "__<size>__"
+            }
+          }
+        }
+      }
+    }
+  }'
+----
+
+. Optional: Publish extensions to the managed registry by editing the `openvsx-server-extensions` `ConfigMap` in the {prod-short} {orch-namespace}. Add extension `.vsix` download URLs, one per line:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} edit configmap openvsx-server-extensions \
+  --namespace {prod-namespace}
+----
++
+The Operator automatically runs a publishing `Job` when the `ConfigMap` content changes.
+
+.Verification
+
+* Verify that the Open VSX server and database pods are running:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-server
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-database
+----
+
+* Access the Open VSX registry UI by navigating to `pass:c,a,q[https://__<che_host>__/openvsx]` in a browser, where `__<che_host>__` is the hostname of your {prod-short} instance. You can retrieve the URL from the `CheCluster` status:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  -o jsonpath='{.status.openVSXURL}'
+----
+
+* Open a workspace and verify that extensions from the managed registry are available in the *Extensions* view.
+
+[id="configuring-custom-credentials-for-the-managed-open-vsx-registry"]
+== 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.
+
+[IMPORTANT]
+====
+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 `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+
+.Procedure
+
+. Create a secret with the required credentials:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} create secret generic __<secret_name>__ \
+  --namespace {prod-namespace} \
+  --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>__
+----
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} label secret __<secret_name>__ \
+  --namespace {prod-namespace} \
+  app.kubernetes.io/part-of=che.eclipse.org
+----
++
+The secret must contain all of the following keys:
++
+[cols="1,2", options="header"]
+|===
+| 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.
+|===
+
+. Reference the secret in the `CheCluster` custom resource:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} patch checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  --type merge \
+  --patch '{
+    "spec": {
+      "components": {
+        "openVSXRegistry": {
+          "enable": true,
+          "credentialsSecretName": "__<secret_name>__"
+        }
+      }
+    }
+  }'
+----
+
+.Verification
+
+. Verify that the Open VSX server pod is running:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-server
+----
+
+. Verify that the custom credentials are injected as environment variables in the Open VSX server pod:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} exec deploy/openvsx-server \
+  --namespace {prod-namespace} -- \
+  env | grep -E 'OPENVSX_ADMIN_PAT|OPENVSX_USER_PAT'
+----
++
+The output should include `OPENVSX_ADMIN_PAT` and `OPENVSX_USER_PAT`.
+
+. Verify that the database pod uses the custom credentials:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} exec deploy/openvsx-database \
+  --namespace {prod-namespace} -- \
+  env | grep -E 'POSTGRESQL_'
+----
+
+[id="customizing-the-open-vsx-server-configuration"]
+== 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 `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+* The managed Open VSX registry is enabled and running.
+
+.Procedure
+
+. Edit the `openvsx-server` `ConfigMap`:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} edit configmap openvsx-server \
+  --namespace {prod-namespace}
+----
++
+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:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-server
+----
+
+[id="deleting-extensions-from-the-managed-open-vsx-registry"]
+== Delete extensions from the managed Open VSX registry
+
+Delete individual extensions or specific extension versions from the managed Open VSX registry by using the Open VSX admin API.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+* The managed Open VSX registry is enabled and running.
+
+.Procedure
+
+. Get the Open VSX server pod name:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-server -o name
+----
+
+. Delete an entire extension with all its versions:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} exec __<openvsx_server_pod>__ \
+  --namespace {prod-namespace} -- \
+  sh -c 'curl -X POST "http://openvsx-server:8080/openvsx/admin/api/extension/__<extension_namespace>__/__<extension_name>__/delete?token=$OPENVSX_ADMIN_PAT"'
+----
++
+where:
++
+--
+`__<openvsx_server_pod>__`:: The pod name from the previous step.
+`__<extension_namespace>__`:: The namespace (publisher) of the extension. For example: `redhat`.
+`__<extension_name>__`:: The name of the extension. For example: `java`.
+--
+
+. Alternatively, to delete only a specific version of an extension:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} exec __<openvsx_server_pod>__ \
+  --namespace {prod-namespace} -- \
+  sh -c 'curl -X POST -H "Content-Type: application/json" \
+  -d '"'"'[{"version": "__<extension_version>__"}]'"'"' \
+  "http://openvsx-server:8080/openvsx/admin/api/extension/__<extension_namespace>__/__<extension_name>__/delete?token=$OPENVSX_ADMIN_PAT"'
+----
++
+where `__<extension_version>__` is the version to delete. For example: `1.2.3`.
+
+.Verification
+
+* Open the Open VSX registry UI and verify that the deleted extension is no longer listed.
+
+[id="disabling-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 {orch-namespace}.
+
+.Prerequisites
+
+* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
+
+.Procedure
+
+. Set the `enable` field to `false`:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} patch checluster {prod-checluster} \
+  --namespace {prod-namespace} \
+  --type merge \
+  --patch '{
+    "spec": {
+      "components": {
+        "openVSXRegistry": {
+          "enable": false
+        }
+      }
+    }
+  }'
+----
++
+The Operator removes all managed Open VSX resources, including deployments, services, persistent volume claims, and secrets.
+
+.Verification
+
+* Verify that no Open VSX pods remain in the {orch-namespace}:
++
+[source,shell,subs="+quotes,+attributes,+macros"]
+----
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-server
+{orch-cli} get pods --namespace {prod-namespace} -l app.kubernetes.io/component=openvsx-database
+----
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:managing-ide-extensions.adoc[]
+* xref:configuring-the-open-vsx-registry-url.adoc[]
+* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]

modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc

@@ -15,6 +15,8 @@ To manage extensions, {prod-short} uses one of the following Open VSX registry i
 
 * A standalone Open VSX registry instance that is deployed on a network accessible from {prod-short} workspace pods.
 
+* An Operator-managed Open VSX registry deployed as a {prod-short} operand. See xref:enabling-the-managed-open-vsx-registry.adoc[].
+
 include::example$snip_{project-context}-default-vsx-registry.adoc[]
 
 include::partial$proc_selecting-an-open-vsx-registry-instance.adoc[leveloffset=+1]