Merge pull request #756 from MichalMaler/i1208-Che_7_Architectural_El…

…ements

Che 7: Che Architecture

src/main/pages/che-7/hands-on-guidance/assembly_che-architectural-elements.adoc

@@ -0,0 +1,14 @@
+:parent-context-of-che-architectural-elements: {context}
+
+[id='che-architectural-elements_{context}']
+= Che architectural elements
+
+:context: che-architectural-elements
+
+include::con_high-level-che-architecture.adoc[leveloffset=+1]
+
+include::assembly_che-workspace-controller.adoc[leveloffset=+1]
+
+include::assembly_che-workspaces.adoc[leveloffset=+1]
+
+:context: {parent-context-of-che-architectural-elements}

src/main/pages/che-7/hands-on-guidance/assembly_che-workspace-components.adoc

@@ -0,0 +1,20 @@
+:parent-context-of-che-workspace-components: {context}
+
+[id='che-workspace-components_{context}']
+= Che workspace components
+
+:context: che-workspace-components
+
+This section describes the components of a Che workspace.
+
+include::con_che-plug-ins.adoc[leveloffset=+1]
+
+include::con_che-editor-plug-in.adoc[leveloffset=+1]
+
+include::con_che-user-runtimes.adoc[leveloffset=+1]
+
+include::con_che-workspace-jwt-proxy.adoc[leveloffset=+1]
+
+include::con_che-plug-in-broker.adoc[leveloffset=+1]
+
+:context: {parent-context-of-che-workspace-components}

src/main/pages/che-7/hands-on-guidance/assembly_che-workspace-configuration.adoc

@@ -0,0 +1,14 @@
+:parent-context-of-che-workspace-configuration: {context}
+
+[id='che-workspace-configuration_{context}']
+= Che workspace configuration
+
+:context: che-workspace-configuration
+
+This section describes the properties of the Che server that affect the provisioning of a Che workspace.
+
+include::con_persistent-volume-configuration.adoc[leveloffset=+1]
+
+include::con_workspaces-namespaces-configuration.adoc[leveloffset=+1]
+
+:context: {parent-context-of-che-workspace-configuration}

src/main/pages/che-7/hands-on-guidance/assembly_che-workspace-controller.adoc

@@ -0,0 +1,31 @@
+:parent-context-of-che-workspace-controller: {context}
+
+[id='che-workspace-controller_{context}']
+= Che workspace controller
+
+:context: che-workspace-controller
+
+The workspaces controller manages the container-based development environments: Che workspaces. It can be deployed in the following distinct configurations:
+
+* *Single-user*: No authentication service is set up. Development environments are not secured. This configuration requires fewer resources. It is more adapted for local installations, such as when using Minikube.
+
+* *Multi-user*: This is a multi-tenant configuration. Development environments are secured, and this configuration requires more resources. Appropriate for cloud installations.
+
+The different services that are a part of the Che workspaces controller are shown in the following diagram. Note that Keycloak and Postgres are only needed in the multi-user configuration.
+
+.Che workspaces controller
+image::architecture/che-workspaces-controllers.png[]
+
+include::con_che-server.adoc[leveloffset=+1]
+
+include::con_che-user-dashboard.adoc[leveloffset=+1]
+
+include::con_che-devfile-registry.adoc[leveloffset=+1]
+
+include::con_che-plug-in-registry.adoc[leveloffset=+1]
+
+include::con_che-postgresql.adoc[leveloffset=+1]
+
+include::con_che-keycloak.adoc[leveloffset=+1]
+
+:context: {parent-context-of-che-workspace-controller}

src/main/pages/che-7/hands-on-guidance/assembly_che-workspaces.adoc

@@ -0,0 +1,27 @@
+:parent-context-of-che-workspaces-architecture: {context}
+
+[id='che-workspaces-architecture_{context}']
+= Che workspaces architecture
+
+:context: che-workspaces-architecture
+
+The Che workspace is a web application. It is composed of microservices running in containers that provide all the services of a modern IDE (an editor, language auto-completion, debugging tooling). The IDE services are deployed with the development tooling, packaged in containers and user runtime applications, which are defined as Kubernetes resources.
+
+The source code of the projects of a Che workspace is persisted in a Kubernetes `PersistentVolume`. Microservices run in containers that have read-write access to the source code (IDE services, development tools), and runtime applications have read-write access to this shared folder.
+
+The following diagram shows the detailed components of a Che workspace.
+
+.Che workspace components
+image::architecture/che-workspaces.png[]
+
+The diagram shows three running workspaces: two belonging to *User A* and one to *User C*. A fourth workspace is getting provisioned where the plug-in broker is verifying and completing the workspace configuration.
+
+Use the devfile format to specify the tools and runtime applications of a Che workspace.
+
+include::assembly_che-workspace-components.adoc[leveloffset=+1]
+
+include::assembly_che-workspace-configuration.adoc[leveloffset=+1]
+
+include::con_che-workspace-creation-flow.adoc[leveloffset=+1]
+
+:context: {parent-context-of-che-workspaces-architecture}

src/main/pages/che-7/hands-on-guidance/assembly_contributor-tasks.adoc

@@ -31,6 +31,8 @@ summary:
 
 // include::proc_adding-support-for-a-new-language.adoc[leveloffset=+1]
 
+include::assembly_che-architectural-elements.adoc[leveloffset=+1]
+
 include::proc_adding-support-for-a-new-debugger.adoc[leveloffset=+1]
 
 // include::proc_packaging-a-visual-studio-code-plug-in-for-che.adoc[leveloffset=+1]

src/main/pages/che-7/hands-on-guidance/con_che-devfile-registry.adoc

@@ -0,0 +1,16 @@
+[id="devfile-registry_{context}"]
+= Devfile registry
+
+The Che devfile registry is a service that provides a list of Che stacks to create ready-to-use workspaces. This list of stacks is used in the  *Dashboard > Create Workspace* window. The devfile registry runs in a container and can be deployed wherever the user dashboard can connect. The default registry: link:https://che-devfile-registry.openshift.io/[che-devfile-registry.openshift.io].
+
+// THIS NEED TO BE FIXED
+For more information about devfile registry customization, see the link:filename_its-assembly[Devfile registry customization] section in the Administration Guide.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che-devfile-registry[Che Devfile registry]
+
+| Container image
+| `quay.io/eclipse/che-devfile-registry`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-editor-plug-in.adoc

@@ -0,0 +1,17 @@
+[id="che-editor-plug-in_{context}"]
+= Che editor plug-in
+
+A Che editor is a special kind of Che workspace plug-in. It defines the web application that is used as an editor in a workspace. The default Che workspace editor is called Eclipse Che-Theia.
+
+The Eclipse Che-Theia source-code repository is at link:https://github.com/eclipse/che-theia[Che Theia Github]. It is based on the link:https://github.com/theia-ide/theia[Eclipse Theia open-source project].
+
+Che-Theia is written in TypeScript and is built on the link:https://github.com/Microsoft/monaco-editor[Microsoft Monaco editor]. It is a web-based source-code editor that looks similar link:https://code.visualstudio.com/[Visual Studio Code]. It has a plug-in system that supports Visual Studio Code extensions.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che-theia[Che Theia]
+
+| Container image
+| `eclipse/che-theia`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-keycloak.adoc

@@ -0,0 +1,15 @@
+[id="che-keycloak_{context}"]
+= Che and Keycloak
+
+Keycloak is a prerequisite to configure Che in multi-user mode. The Che administrator can choose to connect Che to an existing Keycloak instance or let the Che deployment start a new dedicated Keycloak instance.
+
+The Che server uses Keycloak as an OpenID Connect (OIDC) provider to authenticate Che users and secure access to Che resources.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che/tree/master/dockerfiles/keycloak[Che Keycloak]
+
+| Container image
+| `eclipse/che-keycloak`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-plug-in-broker.adoc

@@ -0,0 +1,24 @@
+[id="che-plug-in-broker_{context}"]
+= Che plug-in broker
+
+Plug-in brokers are special services that, given a plug-in `meta.yaml` file:
+
+* Gather all the information to provide a Che plug-in definition that the Che server knows.
+
+* Perform preparation actions in the workspace namespace (download, unpack files, process configuration).
+
+The main goal of the plug-in broker is to decouple the Che plug-in definition from the actual plug-ins that Che can support. With brokers, Che can support different plug-ins without updating the Che server.
+
+The Che server starts the plug-in broker. The plug-in broker runs in the same Kubernetes namespace as the workspace. It has access to the plug-ins and project persistent volumes.
+
+A plug-in broker is defined as a container image (for example, `eclipse/che-plugin-broker`). The plug-in type determines the type of the broker that is started. Two types of plug-ins are supported: Che plug-in and Che editor.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che-plugin-broker[Che Plug-in broker]
+
+| Container image
+| `eclipse/che-init-plugin-broker` +
+`eclipse/che-unified-plugin-broker`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-plug-in-registry.adoc

@@ -0,0 +1,16 @@
+[id="che-plug-in-registry_{context}"]
+= Che plug-in registry
+
+The Che plug-in registry is a service that provides the list of plug-ins and editors for the Che workspaces. A devfile can reference only a plug-in that is published in a Che plug-in registry. It runs in a container and can be deployed wherever wsmaster connects. The default registry: link:https://che-plugin-registry.openshift.io/[che-plugin-registry.openshift.io].
+
+// THIS NEED TO BE FIXED
+For more information about plug-in registry customization, see the link:filename_its-assembly[Devfile registry customization] section in the Administration Guide.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che-devfile-registry[Che Devfile registry]
+
+| Container image
+| `quay.io/eclipse/che-devfile-registry`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-plug-ins.adoc

@@ -0,0 +1,14 @@
+[id="che-plug-ins_{context}"]
+= Che plug-ins
+
+Che plug-ins are special services that extend Che workspace capabilities. Che plug-ins are packaged as containers. Packaging plug-ins into a container has the following benefits:
+
+* It isolates the plug-ins from the main IDE, thus limiting the resources that a plug-in has access to.
+
+* It uses the consolidated standard of container registries to publish and distribute plug-ins (as with any container image).
+
+The containers that plug-ins are packaged into run as sidecars of the Che workspace editor and augment its capabilities.
+
+Visual Studio Code extensions packaged in containers are Che plug-ins for the Che-Theia editor.
+
+Multiple Che plug-ins can run in the same container (for better resource use), or a Che plug-in can run in its dedicated container (for better isolation).

src/main/pages/che-7/hands-on-guidance/con_che-postgresql.adoc

@@ -0,0 +1,15 @@
+[id="che-postgresql_{context}"]
+= Che and PostgreSQL
+
+The PostgreSQL database is a prerequisite to configure Che in multi-user mode. The Che administrator can choose to connect Che to an existing PostgreSQL instance or let the Che deployment start a new dedicated PostgreSQL instance.
+
+The Che server uses the database to persist user configurations (workspaces metadata, Git credentials). Keycloak uses the database as its back end to persist user information.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che/tree/master/dockerfiles/postgres[Che Postgres]
+
+| Container image
+| `eclipse/che-postgres`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-server.adoc

@@ -0,0 +1,13 @@
+[id="che-server_{context}"]
+= Che server
+
+The Che server, also known as *wsmaster*, is the central service of the workspaces controller. It is a Java web service that exposes an HTTP REST API to manage Che workspaces and, in multi-user mode, Che users.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che[Eclipse Che GitHub] 
+
+| Container image
+| `eclipse/che-server`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-user-dashboard.adoc

@@ -0,0 +1,13 @@
+[id="che-user-dashboard_{context}"]
+= Che user dashboard
+
+The user dashboard is the landing page of Eclipse Che. It is an Angular front-end application. Che users create, start, and manage Che workspaces from their browsers through the user dashboard.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che/tree/master/dashboard[Che Dashboard]
+
+| Container image
+| `eclipse/che-server`
+|===

src/main/pages/che-7/hands-on-guidance/con_che-user-runtimes.adoc

@@ -0,0 +1,8 @@
+[id="che-user-runtimes_{context}"]
+= Che user runtimes
+
+Any non-terminating user container can be used as a user runtime. An application that can be defined as a container image or as a set of Kubernetes or OpenShift resources can be included in a Che workspace. This makes it easy to test applications in the Che workspace.
+
+To test an application in the Che workspace, include the application YAML definition used in stage or production in the workspace specification. It is a 12-factor app dev/prod parity.
+
+Examples of user runtimes are NodeJS, SpringBoot or MongoDB, and MySQL.

src/main/pages/che-7/hands-on-guidance/con_che-workspace-creation-flow.adoc

@@ -0,0 +1,22 @@
+[id="che-workspace-creation-flow_{context}"]
+= Che workspace creation flow
+
+image::architecture/che-workspace-creation-flow.png[]
+
+A Che workspace is created in the following way:
+
+. A user starts a Che workspace defined by:
++
+* An editor (the default is Che-Theia)
+* A list of plug-ins (for example, Java and Kubernetes tooling)
+* A list of runtime applications
+
+. *wsmaster* retrieves the editor and plug-in metadata from the plug-in registry.
+. For every plug-in type, *wsmaster* starts a specific plug-in broker.
+. The Che plug-in broker transforms the plug-in metadata into a Che plug-in definition. It executes the following steps:
++
+.. Downloads a plug-in and extracts its content.
+.. Processes the plug-in `meta.yaml` file and sends it back to *wsmaster* in the format of a Che plug-in.
+
+. *wsmaster* starts the editor and the plug-in sidecars.
+. The editor loads the plug-ins from the plug-in persistent volume.

src/main/pages/che-7/hands-on-guidance/con_che-workspace-jwt-proxy.adoc

@@ -0,0 +1,15 @@
+[id="che-workspace-jwt-proxy_{context}"]
+= Che workspace JWT proxy
+
+The JWT proxy is responsible for securing the communication of the Che workspace services. The Che workspace JWT proxy is included in a Che workspace only if the Che server is configured in the multi-user mode.
+
+An HTTP proxy is used to sign outgoing requests from a workspace service to the Che server and to authenticate incoming requests from the IDE client running on a browser.
+
+[cols=2*]
+|===
+| Source code
+| link:https://github.com/eclipse/che-jwtproxy[JWT proxy]
+
+| Container image
+| `eclipse/che-jwtproxy`
+|===

src/main/pages/che-7/hands-on-guidance/con_high-level-che-architecture.adoc

@@ -0,0 +1,11 @@
+[id="high-level-che-architecture_{context}"]
+= High-level Che architecture
+
+.High-level Che architecture
+image::architecture/che-high-level.png[]
+
+At a high-level, Che is composed of one central workspace controller that manages the Che workspaces through the Kubernetes API.
+
+When Che is installed on a Kubernetes cluster, the workspace controller is the only component that is deployed. A Che workspace is created immediately after a user requests it.
+
+This section describes the different services that create the workspaces controller and the Che workspaces.

src/main/pages/che-7/hands-on-guidance/con_persistent-volume-configuration.adoc

@@ -0,0 +1,8 @@
+[id="persistent-volume-configuration_{context}"]
+= Persistent volume configuration
+
+A Kubernetes persistent volume is attached to the Che workspace to persist its data: source code, application logs, and tools configuration. A Che server can be configured to use different strategies:
+
+* *common*: A Che workspace that is provisioned in the same Kubernetes namespace and shares the same `PesistentVolume`. The data of different workspaces are separated using subpaths. The default strategy is *common*.
+
+* *unique*: Every Che workspace is attached to a distinct persistent volume. This strategy provides better data isolation but requires more resources.

src/main/pages/che-7/hands-on-guidance/con_workspaces-namespaces-configuration.adoc

@@ -0,0 +1,4 @@
+[id="workspace-namespaces-configuration_{context}"]
+= Workspace namespaces configuration
+
+The Kubernetes namespace where a new workspace pod is deployed depends on the Che server configuration. By default, every workspace is deployed in a distinct namespace, but the Che server can be configured to deploy all workspaces in one specific namespace. The name of a namespace must be provided as a Che server configuration property and cannot be changed at runtime.