diff --git a/antora.yml b/antora.yml index 2b76f5eff8..805ff2743b 100644 --- a/antora.yml +++ b/antora.yml @@ -7,6 +7,7 @@ start_page: overview:introduction-to-eclipse-che.adoc nav: - modules/overview/nav.adoc - modules/hosted-che/nav.adoc + - modules/discover/nav.adoc - modules/end-user-guide/nav.adoc - modules/administration-guide/nav.adoc - modules/extensions/nav.adoc @@ -133,6 +134,6 @@ ext: - run: command: ./tools/create_architecture_diagrams.py scan: - base: modules/administration-guide/images/architecture/ + base: modules/discover/images/architecture/ dir: build/collector/architecture-diagrams files: '*.png' diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index e26825866c..0b6b8020eb 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -2,18 +2,7 @@ * xref:security-best-practices.adoc[] * xref:preparing-the-installation.adoc[] -** xref:supported-platforms.adoc[] ** xref:installing-the-chectl-management-tool.adoc[] -** xref:architecture-overview.adoc[] -*** xref:server-components.adoc[] -**** xref:che-operator.adoc[] -**** xref:devworkspace-operator.adoc[] -**** xref:gateway.adoc[] -**** xref:dashboard.adoc[] -**** xref:che-server.adoc[] -**** xref:che-devfile-registry.adoc[] -**** xref:plugin-registry.adoc[] -*** xref:user-workspaces.adoc[] ** xref:calculating-che-resource-requirements.adoc[] * xref:running-at-scale.adoc[] // Install diff --git a/modules/administration-guide/pages/architecture-overview.adoc b/modules/administration-guide/pages/architecture-overview.adoc deleted file mode 100644 index 6ce4997086..0000000000 --- a/modules/administration-guide/pages/architecture-overview.adoc +++ /dev/null @@ -1,39 +0,0 @@ -:_content-type: CONCEPT -:description: High-level {prod-short} architecture -:keywords: administration-guide, architecture -:navtitle: Architecture -:page-aliases: .:che-architecture-overview.adoc, .:high-level-che-architecture.adoc, overview:high-level-che-architecture.adoc, administration-guide:high-level-che-architecture.adoc, che-architecture-overview.adoc, .:che-architecture-overview-with-che-server.adoc, .:high-level-che-architecture-with-che-server.adoc, overview:high-level-che-architecture-with-che-server.adoc, administration-guide:high-level-che-architecture-with-che-server.adoc, .:che-architecture-overview-with-devworkspace.adoc, .:high-level-che-architecture-with-devworkspace.adoc, overview:high-level-che-architecture-with-devworkspace.adoc, administration-guide:high-level-che-architecture-with-devworkspace.adoc, architecture-overview-with-devworkspace.adoc, architecture-overview-with-che-server, server-components-with-che-server.adoc, che-workspaces-architecture-with-che-server.adoc, backup-and-recovery.adoc, supported-restic-compatible-backup-servers.adoc, backing-up-of-che-instances-to-an-sftp-backup-server.adoc, backing-up-of-che-instances-to-amazon-s3.adoc, backing-up-of-che-instances-to-a-rest-backup-server.adoc, backing-up-of-che-instances-to-the-internal-backup-server.adoc, restoring-a-che-instance-from-a-backup.adoc, backups-of-persistent-volumes.adoc, readiness-init-containers.adoc, enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-readiness-init-containers-for-the-operator-installer.adoc, disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc, enabling-readiness-init-containers-for-the-olm-installer.adoc, disabling-readiness-init-containers-for-the-olm-installer.adoc, overview:architecture-overview.adoc, overview:che-architecture.adoc - -[id="architecture"] -= {prod-short} architecture - -.High-level {prod-short} architecture with the {devworkspace} operator -image::architecture/{project-context}-interacting-with-devworkspace.png[] - -{prod-short} runs on three groups of components: - -{prod-short} server components:: -Manage User {orch-namespace} and workspaces. The main component is the User dashboard, from which users control their workspaces. - -{devworkspace} operator:: -Creates and controls the necessary {orch-name} objects to run User workspaces. Including `Pods`, `Services`, and `PersistentVolumes`. - -User workspaces:: -Container-based development environments, the IDE included. - -The role of these {orch-name} features is central: - -{devworkspace} Custom Resources:: -Valid {orch-name} objects representing the User workspaces and manipulated by {prod-short}. It is the communication channel for the three groups of components. - -{orch-name} role-based access control (RBAC):: -Controls access to all resources. - -.Additional resources - -* xref:server-components.adoc[] -* xref:devworkspace-operator.adoc[] -* xref:user-workspaces.adoc[] -* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository] - -include::example$snip_che-architecture-overview-with-devworkspace-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/configuring-storage-classes.adoc b/modules/administration-guide/pages/configuring-storage-classes.adoc index 7c6be0de16..8fa5d4d434 100644 --- a/modules/administration-guide/pages/configuring-storage-classes.adoc +++ b/modules/administration-guide/pages/configuring-storage-classes.adoc @@ -22,7 +22,7 @@ Persistent volume claims facts: * {prod-short} does not create persistent volumes in the infrastructure. * {prod-short} uses persistent volume claims (PVC) to mount persistent volumes. -* The xref:devworkspace-operator.adoc[Dev Workspace operator] creates persistent volume claims. +* The xref:discover:devworkspace-operator.adoc[Dev Workspace operator] creates persistent volume claims. + Define a storage class name in the {prod-short} configuration to use the storage classes feature in the {prod-short} PVC. diff --git a/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc b/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc index a7e0cad47b..f84d79eeb9 100644 --- a/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc +++ b/modules/administration-guide/pages/devworkspace-backup-integrated-openshift-registry.adoc @@ -31,7 +31,7 @@ config: schedule: '0 */4 * * *' # cron expression with backup frequency imagePullPolicy: Always ---- -<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview]. +<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview]. <2> The `--insecure` flag can be required depending on the integrated registry's routing configuration. **Note:** The `path` field must contain the URL to your OpenShift integrated registry given by the cluster. diff --git a/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc b/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc index bb680ddb79..12aa7b9009 100644 --- a/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc +++ b/modules/administration-guide/pages/devworkspace-backup-regular-oci-registry.adoc @@ -31,7 +31,7 @@ config: schedule: '0 */4 * * *' imagePullPolicy: Always ---- -<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview]. +<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview]. The `authSecret` must be named `devworkspace-backup-registry-auth`. It must reference a {kubernetes} Secret of type `kubernetes.io/dockerconfigjson` that contains credentials to access the registry. The secret should be created in the installation {namespace} for the {devworkspace} operator. diff --git a/modules/administration-guide/pages/preparing-the-installation.adoc b/modules/administration-guide/pages/preparing-the-installation.adoc index 0e5ff54637..292b2662c5 100644 --- a/modules/administration-guide/pages/preparing-the-installation.adoc +++ b/modules/administration-guide/pages/preparing-the-installation.adoc @@ -7,10 +7,10 @@ [id="preparing-the-installation"] = Preparing the installation -To prepare a {prod-short} installation, learn about the {prod-short} ecosystem and deployment constraints: +To prepare a {prod-short} installation, review the platform requirements and deployment tools: -* xref:supported-platforms.adoc[] +* xref:discover:supported-platforms.adoc[] +* xref:discover:architecture-overview.adoc[] * xref:installing-the-chectl-management-tool.adoc[] -* xref:architecture-overview.adoc[] * xref:calculating-che-resource-requirements.adoc[] * xref:understanding-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/pages/server-components.adoc b/modules/administration-guide/pages/server-components.adoc deleted file mode 100644 index bc1109aed7..0000000000 --- a/modules/administration-guide/pages/server-components.adoc +++ /dev/null @@ -1,21 +0,0 @@ -:_content-type: ASSEMBLY -:description: Server components -:keywords: administration-guide, architecture, server, devworkspace -:navtitle: Server components -:page-aliases: - -[id="{prod-id-short}-server-components"] -= {prod-short} server components - -The {prod-short} server components ensure multi-tenancy and workspaces management. - -.{prod-short} server components interacting with the {devworkspace} operator -image::architecture/{project-context}-deployments-interacting-with-devworkspace.png[] - -.Additional resources - -* xref:che-operator.adoc[] -* xref:gateway.adoc[] -* xref:dashboard.adoc[] -* xref:che-server.adoc[] -* xref:plugin-registry.adoc[] diff --git a/modules/administration-guide/pages/supported-platforms.adoc b/modules/administration-guide/pages/supported-platforms.adoc deleted file mode 100644 index c497139f87..0000000000 --- a/modules/administration-guide/pages/supported-platforms.adoc +++ /dev/null @@ -1,10 +0,0 @@ -:_content-type: REFERENCE -:description: Supported platforms -:keywords: platform, supported-platforms -:navtitle: Supported platforms -:page-aliases: installation-guide:supported-platforms.adoc - -[id="supported-platforms"] -= Supported platforms - -include::example$snip_{project-context}-supported-platforms.adoc[] diff --git a/modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc b/modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc index c2925fa0b0..e9d5159750 100644 --- a/modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc +++ b/modules/administration-guide/partials/snip_defining-dwo-namespace-for-backups.adoc @@ -18,5 +18,5 @@ spec: value: $OPERATOR_INSTALL_NAMESPACE <1> name: che-dashboard ---- -<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:devworkspace-operator.adoc[{devworkspace} operator overview]. +<1> For Red Hat OpenShift, the default installation namespace for the {devworkspace} operator is `openshift-operators`. See the xref:discover:devworkspace-operator.adoc[{devworkspace} operator overview]. ==== diff --git a/modules/administration-guide/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc b/modules/discover/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc rename to modules/discover/examples/snip_che-architecture-overview-with-devworkspace-additional-resources.adoc diff --git a/modules/administration-guide/examples/snip_che-che-server-additional-resources.adoc b/modules/discover/examples/snip_che-che-server-additional-resources.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-che-server-additional-resources.adoc rename to modules/discover/examples/snip_che-che-server-additional-resources.adoc diff --git a/modules/administration-guide/examples/snip_che-dashboard-additional-resources.adoc b/modules/discover/examples/snip_che-dashboard-additional-resources.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-dashboard-additional-resources.adoc rename to modules/discover/examples/snip_che-dashboard-additional-resources.adoc diff --git a/modules/administration-guide/examples/snip_che-devworkspace-additional-resources.adoc b/modules/discover/examples/snip_che-devworkspace-additional-resources.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-devworkspace-additional-resources.adoc rename to modules/discover/examples/snip_che-devworkspace-additional-resources.adoc diff --git a/modules/administration-guide/examples/snip_che-supported-platforms.adoc b/modules/discover/examples/snip_che-supported-platforms.adoc similarity index 94% rename from modules/administration-guide/examples/snip_che-supported-platforms.adoc rename to modules/discover/examples/snip_che-supported-platforms.adoc index bf0a65d623..f30b644056 100644 --- a/modules/administration-guide/examples/snip_che-supported-platforms.adoc +++ b/modules/discover/examples/snip_che-supported-platforms.adoc @@ -23,4 +23,4 @@ The following options are available for the local installation: .Additional resources -* xref:installing-che.adoc[] +* xref:administration-guide:installing-che.adoc[] diff --git a/modules/administration-guide/images/devworkspace-operator/devworkspace-config-attribute.png b/modules/discover/images/devworkspace-operator/devworkspace-config-attribute.png similarity index 100% rename from modules/administration-guide/images/devworkspace-operator/devworkspace-config-attribute.png rename to modules/discover/images/devworkspace-operator/devworkspace-config-attribute.png diff --git a/modules/administration-guide/images/devworkspace-operator/devworkspace-cr-example.png b/modules/discover/images/devworkspace-operator/devworkspace-cr-example.png similarity index 100% rename from modules/administration-guide/images/devworkspace-operator/devworkspace-cr-example.png rename to modules/discover/images/devworkspace-operator/devworkspace-cr-example.png diff --git a/modules/administration-guide/images/workspace-components-with-dw.png b/modules/discover/images/workspace-components-with-dw.png similarity index 100% rename from modules/administration-guide/images/workspace-components-with-dw.png rename to modules/discover/images/workspace-components-with-dw.png diff --git a/modules/discover/nav.adoc b/modules/discover/nav.adoc new file mode 100644 index 0000000000..d21c3f643b --- /dev/null +++ b/modules/discover/nav.adoc @@ -0,0 +1,13 @@ +.Discover + +* xref:architecture-overview.adoc[] +** xref:server-components.adoc[] +*** xref:che-operator.adoc[] +*** xref:devworkspace-operator.adoc[] +*** xref:gateway.adoc[] +*** xref:dashboard.adoc[] +*** xref:che-server.adoc[] +*** xref:che-devfile-registry.adoc[] +*** xref:plugin-registry.adoc[] +** xref:user-workspaces.adoc[] +* xref:supported-platforms.adoc[] diff --git a/modules/discover/pages/architecture-overview.adoc b/modules/discover/pages/architecture-overview.adoc new file mode 100644 index 0000000000..211e9c22e0 --- /dev/null +++ b/modules/discover/pages/architecture-overview.adoc @@ -0,0 +1,42 @@ +:_content-type: CONCEPT +:description: {prod-short} runs on three groups of components — server components, the {devworkspace} Operator, and user workspaces — that communicate through {devworkspace} custom resources on {orch-name}. +:keywords: architecture, discover, components, devworkspace +:navtitle: Architecture overview +:page-aliases: administration-guide:architecture-overview.adoc, .:che-architecture-overview.adoc, .:high-level-che-architecture.adoc, overview:high-level-che-architecture.adoc, administration-guide:high-level-che-architecture.adoc, che-architecture-overview.adoc, .:che-architecture-overview-with-che-server.adoc, .:high-level-che-architecture-with-che-server.adoc, overview:high-level-che-architecture-with-che-server.adoc, administration-guide:high-level-che-architecture-with-che-server.adoc, .:che-architecture-overview-with-devworkspace.adoc, .:high-level-che-architecture-with-devworkspace.adoc, overview:high-level-che-architecture-with-devworkspace.adoc, administration-guide:high-level-che-architecture-with-devworkspace.adoc, architecture-overview-with-devworkspace.adoc, architecture-overview-with-che-server, server-components-with-che-server.adoc, che-workspaces-architecture-with-che-server.adoc, backup-and-recovery.adoc, supported-restic-compatible-backup-servers.adoc, backing-up-of-che-instances-to-an-sftp-backup-server.adoc, backing-up-of-che-instances-to-amazon-s3.adoc, backing-up-of-che-instances-to-a-rest-backup-server.adoc, backing-up-of-che-instances-to-the-internal-backup-server.adoc, restoring-a-che-instance-from-a-backup.adoc, backups-of-persistent-volumes.adoc, readiness-init-containers.adoc, enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-readiness-init-containers-for-the-operator-installer.adoc, disabling-readiness-init-containers-for-the-operator-installer.adoc, enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc, enabling-readiness-init-containers-for-the-olm-installer.adoc, disabling-readiness-init-containers-for-the-olm-installer.adoc, overview:architecture-overview.adoc, overview:che-architecture.adoc + +[id="architecture"] += {prod-short} architecture + +[role="_abstract"] +{prod-short} runs on three groups of components — server components, the {devworkspace} Operator, and user workspaces — that communicate through {devworkspace} custom resources on {orch-name}. Each group has a distinct role in delivering cloud development environments, and {orch-name} RBAC controls access to all resources. + +.High-level {prod-short} architecture with the {devworkspace} operator +image::architecture/{project-context}-interacting-with-devworkspace.png[] + +{prod-short} runs on three groups of components: + +{prod-short} server components:: +Manage User {orch-namespace} and workspaces. The main component is the User dashboard, from which users control their workspaces. + +{devworkspace} operator:: +Creates and controls the necessary {orch-name} objects to run User workspaces. Including `Pods`, `Services`, and `PersistentVolumes`. + +User workspaces:: +Container-based development environments, the IDE included. + +The role of these {orch-name} features is central: + +{devworkspace} Custom Resources:: +Valid {orch-name} objects representing the User workspaces and manipulated by {prod-short}. It is the communication channel for the three groups of components. + +{orch-name} role-based access control (RBAC):: +Controls access to all resources. + +.Additional resources + +* xref:server-components.adoc[] +* xref:devworkspace-operator.adoc[] +* xref:user-workspaces.adoc[] +* link:https://github.com/devfile/devworkspace-operator[{devworkspace} Operator repository] + +include::example$snip_che-architecture-overview-with-devworkspace-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/che-devfile-registry.adoc b/modules/discover/pages/che-devfile-registry.adoc similarity index 60% rename from modules/administration-guide/pages/che-devfile-registry.adoc rename to modules/discover/pages/che-devfile-registry.adoc index c9176db5f1..b118755bf4 100644 --- a/modules/administration-guide/pages/che-devfile-registry.adoc +++ b/modules/discover/pages/che-devfile-registry.adoc @@ -1,12 +1,15 @@ :_content-type: CONCEPT -:description: Devfile registry -:keywords: administration-guide, devfile +:description: The devfile registry provides a list of sample devfiles for creating ready-to-use workspaces. +:keywords: devfile, registry, samples, discover :navtitle: Devfile registry -:page-aliases: +:page-aliases: administration-guide:che-devfile-registry.adoc [id="devfile-registry"] = Devfile registry +[role="_abstract"] +The devfile registry provides a list of sample devfiles for creating ready-to-use workspaces. Use these samples as starting points for your development environments. + A devfile registry is a service providing a list of sample devfiles. You can use these samples to create ready-to-use workspaces. diff --git a/modules/administration-guide/pages/che-operator.adoc b/modules/discover/pages/che-operator.adoc similarity index 51% rename from modules/administration-guide/pages/che-operator.adoc rename to modules/discover/pages/che-operator.adoc index f8ab47018e..b539c9c6b0 100644 --- a/modules/administration-guide/pages/che-operator.adoc +++ b/modules/discover/pages/che-operator.adoc @@ -1,13 +1,16 @@ :_content-type: ASSEMBLY -:description: Components of {prod-short} operator -:keywords: administration-guide, architecture, operator +:description: The {prod-short} Operator manages the full lifecycle of {prod-short} server components through the CheCluster custom resource. +:keywords: operator, architecture, lifecycle, discover :navtitle: {prod-short} operator -:page-aliases: +:page-aliases: administration-guide:che-operator.adoc [id="{prod-id-short}-operator"] = {prod-short} operator -The {prod-short} operator ensure full lifecycle management of the {prod-short} server components. +[role="_abstract"] +The {prod-short} Operator manages the full lifecycle of {prod-short} server components through the `CheCluster` custom resource. Creating a `CheCluster` CR triggers the Operator to deploy the {devworkspace} Operator, gateway, dashboard, server, and plug-in registry. + +The {prod-short} operator ensures full lifecycle management of the {prod-short} server components. It introduces: `CheCluster` custom resource definition (CRD):: @@ -28,5 +31,5 @@ On a cluster with the {prod-short} operator, it is possible to create a `CheClus .Additional resources -* xref:understanding-the-checluster-custom-resource.adoc[] -* xref:installing-che.adoc[] +* xref:administration-guide:understanding-the-checluster-custom-resource.adoc[] +* xref:administration-guide:installing-che.adoc[] diff --git a/modules/administration-guide/pages/che-server.adoc b/modules/discover/pages/che-server.adoc similarity index 56% rename from modules/administration-guide/pages/che-server.adoc rename to modules/discover/pages/che-server.adoc index 22d5f9e9b9..89ae21c6c4 100644 --- a/modules/administration-guide/pages/che-server.adoc +++ b/modules/discover/pages/che-server.adoc @@ -1,12 +1,14 @@ :_content-type: ASSEMBLY -:description: Functions of {prod-short} server -:keywords: administration-guide, architecture, server, devworkspace +:description: The {prod-short} server is a Java web service that creates user namespaces, provisions them with secrets and config maps, and integrates with Git service providers. +:keywords: server, architecture, namespaces, git, discover :navtitle: {prod-short} server -:page-aliases: +:page-aliases: administration-guide:che-server.adoc [id="{prod-id-short}-server-with-devworkspace"] = {prod-short} server +[role="_abstract"] +The {prod-short} server is a Java web service that creates user namespaces, provisions them with secrets and config maps, and integrates with Git service providers for devfile fetching and authentication. The {prod-short} server main functions are: @@ -24,6 +26,6 @@ image::architecture/{project-context}-server-interactions.png[{prod-short} serve .Additional resources -* xref:advanced-configuration-options-for-the-che-server-component.adoc[] +* xref:administration-guide:advanced-configuration-options-for-the-che-server-component.adoc[] include::example$snip_{project-context}-che-server-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/dashboard.adoc b/modules/discover/pages/dashboard.adoc similarity index 73% rename from modules/administration-guide/pages/dashboard.adoc rename to modules/discover/pages/dashboard.adoc index bc5fed5400..dc35d5420a 100644 --- a/modules/administration-guide/pages/dashboard.adoc +++ b/modules/discover/pages/dashboard.adoc @@ -1,12 +1,15 @@ :_content-type: ASSEMBLY -:description: User dashboard -:keywords: administration-guide, architecture, server, devworkspace, user, dashboard +:description: The user dashboard is the landing page of {prod} where users create, manage, and access their workspaces. +:keywords: dashboard, architecture, user interface, discover :navtitle: User dashboard -:page-aliases: +:page-aliases: administration-guide:dashboard.adoc [id="dashboard"] = User dashboard +[role="_abstract"] +The user dashboard is the landing page of {prod} where users create, manage, and access their workspaces. It coordinates with the {prod-short} server, plug-in registry, and {orch-name} API to convert devfiles into running workspace pods. + The user dashboard is the landing page of {prod}. {prod-short} users browse the user dashboard to access and manage their workspaces. It is a React application. diff --git a/modules/administration-guide/pages/devworkspace-operator.adoc b/modules/discover/pages/devworkspace-operator.adoc similarity index 75% rename from modules/administration-guide/pages/devworkspace-operator.adoc rename to modules/discover/pages/devworkspace-operator.adoc index 6b4c7664d0..d1e3fce989 100644 --- a/modules/administration-guide/pages/devworkspace-operator.adoc +++ b/modules/discover/pages/devworkspace-operator.adoc @@ -1,29 +1,27 @@ :_content-type: ASSEMBLY -:description: {devworkspace} operator -:keywords: administration-guide, workspace operator, devworkspace +:description: The {devworkspace} Operator (DWO) extends {orch-name} to manage workspace pods, services, and persistent volumes by reconciling {devworkspace} custom resources. +:keywords: devworkspace, operator, architecture, discover :navtitle: {devworkspace} operator -:page-aliases: .:devworkspace-operator.adoc +:page-aliases: administration-guide:devworkspace-operator.adoc, .:devworkspace-operator.adoc [id="devworkspace-operator"] = {devworkspace} Operator overview - -The {devworkspace} Operator (DWO) is a dependency of {prod-short}, and is an integral part of how {prod-short} functions. One of DWO's main responsibilities is to reconcile {devworkspace} custom resources (CR). +[role="_abstract"] +The {devworkspace} Operator (DWO) extends {orch-name} to manage workspace pods, services, and persistent volumes by reconciling {devworkspace} custom resources. Every {prod-short} workspace has an underlying {devworkspace} CR that contains the devfile, editor definition, and configuration attributes. The {devworkspace} CR is a {orch-name} resource representation of a {prod-short} workspace. Whenever a user creates a workspace using {prod-short} in the background, Dashboard {prod-short} creates a {devworkspace} CR in the cluster. For every {prod-short} workspace, there is an underlying {devworkspace} CR on the cluster. -Figure 1 shows an example of a {devworkspace} CR in a cluster: - .Example of a {devworkspace} CR in a cluster image::devworkspace-operator/devworkspace-cr-example.png[DevWorkspace CR example,width=624,height=465] -When creating a workspace with {prod-short} with a devfile, the {devworkspace} CR contains the devfile details. Additionally, {prod-short} adds the editor definition into the {devworkspace} CR depending on which editor was chosen for the workspace. {prod-short} will also add attributes to the {devworkspace} which further configures the workspace depending on how you configured the `CheCluster` CR. +When creating a workspace with {prod-short} with a devfile, the {devworkspace} CR contains the devfile details. Additionally, {prod-short} adds the editor definition into the {devworkspace} CR depending on which editor was chosen for the workspace. {prod-short} also adds attributes to the {devworkspace} that further configure the workspace depending on how you configured the `CheCluster` CR. A `DevWorkspaceTemplate` is a custom resource that defines a reusable `spec.template` for {devworkspace}s. -When a workspace is started, DWO reads the corresponding {devworkspace} CR and creates the necessary resources such as deployments, secrets, configmaps, routes such that at the end a workspace pod representing the development environment defined in the devfile is created. +When a workspace is started, DWO reads the corresponding {devworkspace} CR and creates the necessary resources such as deployments, secrets, configmaps, and routes. As a result, a workspace pod representing the development environment defined in the devfile is created. -.Custom Resources overview +== Custom Resources overview The following Custom Resource Definitions are provided by the {devworkspace} Operator: @@ -33,22 +31,22 @@ The following Custom Resource Definitions are provided by the {devworkspace} Ope * `DevWorkspaceRouting` -.{devworkspace} +== {devworkspace} The {devworkspace} custom resource contains details about an {prod-short} workspace. Notably, it contains devfile details and a reference to the editor definition. -.DevWorkspaceTemplate +== DevWorkspaceTemplate In {prod-short} the `DevWorkspaceTemplate` custom resource is typically used to define an editor (such as Visual Studio Code - Open Source) for {prod-short} workspaces. You can use this custom resource to define reusable `spec.template` content that is reused by multiple {devworkspace}s. -.DevWorkspaceOperatorConfig +== DevWorkspaceOperatorConfig The `DevWorkspaceOperatorConfig` (DWOC) custom resource defines configuration options for the DWO. There are two different types of DWOC: * global configuration * non-global configuration -The global configuration is a DWOC custom resource named `devworkspace-operator-config` and is usually located in the DWO installation namespace. By default, the global configuration is not created upon installation. Configuration fields set in the global configuration will apply to the DWO and all {devworkspace}s. However, the DWOC configuration can be overridden by a non-global configuration. +The global configuration is a DWOC custom resource named `devworkspace-operator-config` and is usually located in the DWO installation namespace. By default, the global configuration is not created upon installation. Configuration fields set in the global configuration apply to the DWO and all {devworkspace}s. However, the DWOC configuration can be overridden by a non-global configuration. Any other DWOC custom resource than `devworkspace-operator-config` is considered to be non-global configuration. A non-global configuration does not apply to any {devworkspace}s unless the {devworkspace} contains a reference to the DWOC. If the global configuration and non-global configuration have the same fields, the non-global configuration field takes precedence. @@ -69,9 +67,9 @@ For example, by default {prod-short} creates and manages a non-global DWOC in th .Example of {devworkspace} configuration attribute image::devworkspace-operator/devworkspace-config-attribute.png[DevWorkspace config attribute example,width=624,height=280] -.DevWorkspaceRouting +== DevWorkspaceRouting -The `DevWorkspaceRouting` custom resource defines details about the endpoints of a {devworkspace}. Every {devworkspace} has its corresponding `DevWorkspaceRouting` object that specifies the workspace's container endpoints. Endpoints defined from the devfile, as well as endpoints defined by the editor definition will appear in the `DevWorkspaceRouting` custom resource. +The `DevWorkspaceRouting` custom resource defines details about the endpoints of a {devworkspace}. Every {devworkspace} has its corresponding `DevWorkspaceRouting` object that specifies the workspace's container endpoints. Endpoints defined from the devfile, as well as endpoints defined by the editor definition appear in the `DevWorkspaceRouting` custom resource. [source,yaml] ---- @@ -105,26 +103,29 @@ status: ... ---- -== {devworkspace} Operator's operands +== {devworkspace} Operator operands The {devworkspace} Operator has two operands: * controller deployment * webhook deployment. -[source,terminal] +[source,bash] ---- $ oc get pods -l 'app.kubernetes.io/part-of=devworkspace-operator' -o custom-columns=NAME:.metadata.name -n openshift-operators NAME -devworkspace-controller-manager-66c6f674f5-l7rhj <1> -devworkspace-webhook-server-d4958d9cd-gh7vr <2> -devworkspace-webhook-server-d4958d9cd-rfvj6 <2> +devworkspace-controller-manager-66c6f674f5-l7rhj +devworkspace-webhook-server-d4958d9cd-gh7vr +devworkspace-webhook-server-d4958d9cd-rfvj6 ---- -<1> The {devworkspace} controller pod, which is responsible for reconciling custom resources -<2> The {devworkspace} operator webhook server pods +where: + +`devworkspace-controller-manager-*`:: The {devworkspace} controller pod, which is responsible for reconciling custom resources. -.Configuring the {devworkspace}-controller-manager deployment +`devworkspace-webhook-server-*`:: The {devworkspace} operator webhook server pods. + +== Configuring the {devworkspace}-controller-manager deployment You can configure the `devworkspace-controller-manager` pod in the {devworkspace} Operator Subscription object: @@ -149,9 +150,7 @@ spec: cpu: ... ---- -Learn more about configuration in this link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md[documentation]. - -.Configuring the {devworkspace}-webhook-server deployment +== Configuring the {devworkspace}-webhook-server deployment You can configure the `devworkspace-webhook-server` deployment in the global DWOC: @@ -171,4 +170,6 @@ config: .Additional resources +* link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md[Operator Lifecycle Manager Subscription configuration] + include::example$snip_{project-context}-devworkspace-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/gateway.adoc b/modules/discover/pages/gateway.adoc similarity index 55% rename from modules/administration-guide/pages/gateway.adoc rename to modules/discover/pages/gateway.adoc index c357b00720..0ceb9c4332 100644 --- a/modules/administration-guide/pages/gateway.adoc +++ b/modules/discover/pages/gateway.adoc @@ -1,13 +1,16 @@ :_content-type: ASSEMBLY -:description: Gateway -:keywords: administration-guide, architecture, server, devworkspace, gateway +:description: The {prod-short} gateway routes requests, authenticates users with OpenID Connect (OIDC), and enforces {orch-name} RBAC policies. +:keywords: gateway, architecture, traefik, authentication, discover :navtitle: Gateway -:page-aliases: +:page-aliases: administration-guide:gateway.adoc [id="gateway"] = Gateway -The {prod-short} gateway has following roles: +[role="_abstract"] +The {prod-short} gateway routes requests, authenticates users with OpenID Connect (OIDC), and enforces {orch-name} RBAC policies. It controls access to the dashboard, server, plug-in registry, and every user workspace. + +The {prod-short} gateway has the following roles: * Routing requests. It uses link:https://github.com/traefik/traefik[Traefik]. @@ -29,4 +32,4 @@ image::architecture/{project-context}-gateway-interactions.png[{prod-short} gate .Additional resources -* xref:managing-identities-and-authorizations.adoc[] +* xref:administration-guide:managing-identities-and-authorizations.adoc[] diff --git a/modules/administration-guide/pages/plugin-registry.adoc b/modules/discover/pages/plugin-registry.adoc similarity index 60% rename from modules/administration-guide/pages/plugin-registry.adoc rename to modules/discover/pages/plugin-registry.adoc index a490580df0..6845be0ffb 100644 --- a/modules/administration-guide/pages/plugin-registry.adoc +++ b/modules/discover/pages/plugin-registry.adoc @@ -1,12 +1,15 @@ :_content-type: CONCEPT -:description: Plug-in registry -:keywords: administration-guide, architecture, server, devworkspace, plugin, registry -:navtitle: Plug-in registry -:page-aliases: plug-in-registry +:description: The {prod-short} plug-in registry provides the list of available editors and editor extensions, each described by a Devfile v2. +:keywords: plugin, registry, editors, extensions, discover +:navtitle: Plugin registry +:page-aliases: administration-guide:plugin-registry.adoc, plug-in-registry [id="plugin-registry"] = Plugin registry +[role="_abstract"] +The {prod-short} plug-in registry provides the list of available editors and editor extensions, each described by a Devfile v2. The dashboard reads this registry when assembling the {devworkspace} custom resource for a new workspace. + Each {prod-short} workspace starts with a specific editor and set of associated extensions. The {prod-short} plugin registry provides the list of available editors and editor extensions. A Devfile v2 describes each editor or extension. diff --git a/modules/discover/pages/server-components.adoc b/modules/discover/pages/server-components.adoc new file mode 100644 index 0000000000..e6e0bd7c85 --- /dev/null +++ b/modules/discover/pages/server-components.adoc @@ -0,0 +1,22 @@ +:_content-type: ASSEMBLY +:description: The {prod-short} server components manage multi-tenancy and workspace lifecycle. Understanding these components helps you troubleshoot issues and plan cluster capacity. +:keywords: architecture, server, components, devworkspace, discover +:navtitle: Server components +:page-aliases: administration-guide:server-components.adoc + +[id="{prod-id-short}-server-components"] += {prod-short} server components + +[role="_abstract"] +The {prod-short} server components manage multi-tenancy and workspace lifecycle. Understanding these components helps you troubleshoot issues and plan cluster capacity. + +.{prod-short} server components interacting with the {devworkspace} operator +image::architecture/{project-context}-deployments-interacting-with-devworkspace.png[] + +.Additional resources + +* xref:che-operator.adoc[] +* xref:gateway.adoc[] +* xref:dashboard.adoc[] +* xref:che-server.adoc[] +* xref:plugin-registry.adoc[] diff --git a/modules/discover/pages/supported-platforms.adoc b/modules/discover/pages/supported-platforms.adoc new file mode 100644 index 0000000000..4a1baa35ce --- /dev/null +++ b/modules/discover/pages/supported-platforms.adoc @@ -0,0 +1,13 @@ +:_content-type: REFERENCE +:description: {prod-short} runs on a specific range of {orch-name} versions and CPU architectures. +:keywords: platforms, compatibility, supported, discover +:navtitle: Supported platforms +:page-aliases: administration-guide:supported-platforms.adoc, installation-guide:supported-platforms.adoc + +[id="supported-platforms"] += Supported platforms + +[role="_abstract"] +{prod-short} runs on a specific range of {orch-name} versions and CPU architectures. Confirm that your target cluster matches a supported combination before starting the installation. + +include::example$snip_{project-context}-supported-platforms.adoc[] diff --git a/modules/administration-guide/pages/user-workspaces.adoc b/modules/discover/pages/user-workspaces.adoc similarity index 71% rename from modules/administration-guide/pages/user-workspaces.adoc rename to modules/discover/pages/user-workspaces.adoc index ce9f2a2f2d..c854f79b93 100644 --- a/modules/administration-guide/pages/user-workspaces.adoc +++ b/modules/discover/pages/user-workspaces.adoc @@ -1,12 +1,15 @@ :_content-type: REFERENCE -:description: User workspaces -:keywords: administration-guide, architecture, workspace, devworkspace +:description: User workspaces provide browser-based IDEs running in {orch-name} containers, giving developers on-demand access to editors, language servers, debugging tools, and application runtimes. +:keywords: workspaces, architecture, devworkspace, discover :navtitle: User workspaces -:page-aliases: +:page-aliases: administration-guide:user-workspaces.adoc [id="user-workspaces"] = User workspaces +[role="_abstract"] +User workspaces provide browser-based IDEs running in {orch-name} containers, giving developers on-demand access to editors, language servers, debugging tools, and application runtimes without local setup. + .User workspaces interactions with other components image::architecture/{project-context}-user-workspaces-interactions.png[User workspaces interactions with other components] diff --git a/modules/overview/pages/introduction-to-eclipse-che.adoc b/modules/overview/pages/introduction-to-eclipse-che.adoc index 1319cda5a0..4975c80f52 100644 --- a/modules/overview/pages/introduction-to-eclipse-che.adoc +++ b/modules/overview/pages/introduction-to-eclipse-che.adoc @@ -21,10 +21,10 @@ == Getting started with {prod-short} * xref:what-is-{prod-id-short}[] -* xref:architecture-overview.adoc[] +* xref:discover:architecture-overview.adoc[] * xref:hosted-che:hosted-che.adoc[] * xref:administration-guide:installing-che.adoc[] -* xref:administration-guide:supported-platforms.adoc[] +* xref:discover:supported-platforms.adoc[] * xref:administration-guide:calculating-che-resource-requirements.adoc[] @@ -96,4 +96,4 @@ Developers using {prod} use their containers directly in their developer workspa .Additional resources -* xref:architecture-overview.adoc[] +* xref:discover:architecture-overview.adoc[]