diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 844c4820c7..d397c0c880 100644 --- a/modules/administration-guide/nav.adoc +++ b/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[] 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..88410dfb81 --- /dev/null +++ b/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": "____" + } + } + } + } + } + }' +---- ++ +where `____` 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": "____" + } + } + } + } + } + }' +---- + +. 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://____/openvsx]` in a browser, where `____` 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 ____ \ + --namespace {prod-namespace} \ + --from-literal=database-user=____ \ + --from-literal=database-password=____ \ + --from-literal=database-name=____ \ + --from-literal=openvsx-publisher-name=____ \ + --from-literal=openvsx-publisher-token=____ \ + --from-literal=openvsx-admin-name=____ \ + --from-literal=openvsx-admin-token=____ +---- ++ +[source,shell,subs="+quotes,+attributes,+macros"] +---- +{orch-cli} label secret ____ \ + --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": "____" + } + } + } + }' +---- + +.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 ____ \ + --namespace {prod-namespace} -- \ + sh -c 'curl -X POST "http://openvsx-server:8080/openvsx/admin/api/extension/____/____/delete?token=$OPENVSX_ADMIN_PAT"' +---- ++ +where: ++ +-- +`____`:: The pod name from the previous step. +`____`:: The namespace (publisher) of the extension. For example: `redhat`. +`____`:: 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 ____ \ + --namespace {prod-namespace} -- \ + sh -c 'curl -X POST -H "Content-Type: application/json" \ + -d '"'"'[{"version": "____"}]'"'"' \ + "http://openvsx-server:8080/openvsx/admin/api/extension/____/____/delete?token=$OPENVSX_ADMIN_PAT"' +---- ++ +where `____` 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[] diff --git a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc b/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc index bf8486108d..62798b03f4 100644 --- a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc +++ b/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] diff --git a/modules/administration-guide/pages/managing-ide-extensions.adoc b/modules/administration-guide/pages/managing-ide-extensions.adoc index 5ddb74e2b4..7b5d8a0f03 100644 --- a/modules/administration-guide/pages/managing-ide-extensions.adoc +++ b/modules/administration-guide/pages/managing-ide-extensions.adoc @@ -12,19 +12,24 @@ Manage IDE extensions in {prod-short} workspaces to control which extensions are IDEs in {prod-short} use extensions to provide language support, debugging, linting, and other development tools. The Microsoft Visual Studio Code - Open Source editor manages extensions through the Open VSX registry. -{prod-short} supports three registry configurations: +{prod-short} supports five registry configurations: -Embedded Open VSX registry:: Runs in the `plugin-registry` pod and supports air-gapped, offline, and proxy-restricted environments. Contains a default subset of extensions that you can customize. +. *Embedded Open VSX registry*. Runs in the `plugin-registry` pod and supports air-gapped, offline, and proxy-restricted environments. Contains a default subset of extensions that you can customize. -Public Open VSX registry:: The community-hosted registry at `open-vsx.org`, accessed over the internet. Provides the full catalog of openly published extensions. +. *Public Open VSX registry*. The community-hosted registry at `open-vsx.org`, accessed over the internet. Provides the full catalog of openly published extensions. -Standalone Open VSX registry:: A self-hosted instance deployed on a network accessible from {prod-short} workspace pods. Provides full control over available extensions for organizations that need a curated, private registry. +. *Standalone Open VSX registry*. A self-hosted instance deployed on a network accessible from {prod-short} workspace pods. Provides full control over available extensions for organizations that need a curated, private registry. + +. *Operator-managed Open VSX registry*. An Open VSX server and PostgreSQL database deployed and managed by the {prod-short} Operator as cluster operands. The Operator handles provisioning, database setup, exposure through the {prod-short} gateway, and lifecycle management. Enable it by setting `spec.components.openVSXRegistry.enable` in the `CheCluster` custom resource. + +. *Managed Open VSX registry*. A commercially supported, hosted registry operated by the Eclipse Foundation. Provides a cloud-hosted Open VSX registry without requiring self-hosted infrastructure. See link:https://managed.open-vsx.org/pricing/[Open VSX Managed Registry] for available plans. [role="_additional-resources"] .Additional resources * 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[]