Merge pull request #105 from stakater/devworkspace-metadata

Adding guide on how to DevWorkspace metadata
stakater · Mar 11, 2024 · d936b17 · d936b17
2 parents 580a27b + d5604cf
commit d936b17
Show file tree

Hide file tree

Showing 8 changed files with 233 additions and 19 deletions.
diff --git a/.vale.ini b/.vale.ini
@@ -1,4 +1,4 @@
-StylesPath = styles
+#StylesPath = styles
 MinAlertLevel = warning
 
 Packages = https://github.com/stakater/vale-package/releases/download/v0.0.9/Stakater.zip

diff --git a/README.md b/README.md
@@ -2,16 +2,15 @@
 
 Documentation for [Multi Tenant Operator](https://www.stakater.com/mto)
 
-
 SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python.
 
 ## GitHub Actions
 
 This repository has GitHub action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.
 
 ## How to make changes
-It is important to know that you should only make changes in `theme_override` and `content` directory. Also, be mindful of which `mkdocs.yml` file you change since there are more than one such files.
 
+It is important to know that you should only make changes in `theme_override` and `content` directory. Also, be mindful of which `mkdocs.yml` file you change since there are more than one such files.
 
 ## Take update on git submodule
 
@@ -28,7 +27,7 @@ view `.gitmodules` file to see linked git submodules.
 There are at least three options to get fast continuous feedback during local development:
 
 1. Build and run the docs using the Dockerfile image
-2. Run the commands locally
+1. Run the commands locally
 
 ### Build Dockerfile image and run container
 
@@ -57,48 +56,50 @@ Install python environment dependencies if you are using any other than what is
 Then run below script to prepare theme from local and common theme resources. It will output to `dist/_theme` directory and create `mkdocs.yml` file in root directory. We are also installing the python dependencies coming from `theme_common` here.
 
 ```bash
-$ ./prepare_theme.sh
+./prepare_theme.sh
 ```
 
 Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
 
 ```bash
-$ mkdocs serve
+mkdocs serve
 ```
 
 or
 
 ```bash
-$ python3 -m mkdocs serve
+python3 -m mkdocs serve
 ```
 
 if you want to make theme changes with live reload, you can use `--watch-theme` with serve like below:
+
 ```bash
-$ mkdocs serve --watch-theme
+mkdocs serve --watch-theme
 ```
-Then, you can make changes in `content` or `dist/_theme` folder. Please note that `dist/_theme` is a build folder and any changes made here will be lost if you do not move them to theme_common or theme_override folder.
 
+Then, you can make changes in `content` or `dist/_theme` folder. Please note that `dist/_theme` is a build folder and any changes made here will be lost if you do not move them to theme_common or theme_override folder.
 
 ### QA Checks
 
 Markdown linting:
 
 ```bash
-$ brew install markdownlint-cli
-$ markdownlint -c .markdownlint.yaml content
+brew install markdownlint-cli
+markdownlint -c .markdownlint.yaml content
 ```
 
 Spell checking:
 
 ```bash
-$ brew install vale
-$ vale content
+brew install vale
+vale sync
+vale content
 ```
 
 ## Use Tilt
 
 Install [Tilt](https://docs.tilt.dev/index.html), then run:
 
 ```bash
-$ tilt up
-```
+tilt up
+```
diff --git a/content/how-to-guides/tenant.md b/content/how-to-guides/tenant.md
@@ -70,6 +70,11 @@ spec:
         stakater.com/sandbox: true
       namespaces: # optional
         - alpha-dave-stakater-sandbox
+  sandboxMetadata: # optional
+    labels: # optional
+      app.kubernetes.io/part-of: che.eclipse.org
+    annotations: # optional
+      che.eclipse.org/username: "{{ TENANT.USERNAME }}" # templated placeholder
   templateInstances: # optional
   - spec: # optional
       template: networkpolicy # required
@@ -123,6 +128,10 @@ spec:
     * `annotations` distributes given annotations among specific tenant namespaces
     * `namespaces` consists a list of specific tenant namespaces across which the labels and annotations will be distributed
 
+* `sandboxMetadata` can be used to distribute specific labels and annotations among all tenant sandbox namespaces.
+    * `labels` distributes given labels among tenant sandbox namespaces
+    * `annotations` distributes given annotations among tenant sandbox namespaces. In annotations, we also support a username template `{{ TENANT.USERNAME }}`, it can be used if you want to access tenant username value in annotation i.e. `username: {{ TENANT.USERNAME }}`. This template can be used for `sandboxMetadata` labels as well, given that username is valid for a label value.
+
 * Tenant automatically deploys `template` resource mentioned in `templateInstances` to matching tenant namespaces.
     * `Template` resources are created in those `namespaces` which belong to a `tenant` and contain `matching labels`.
     * `Template` resources are created in all `namespaces` of a `tenant` if `selector` field is empty.

diff --git a/content/reference-guides/templated-metadata-values.md b/content/reference-guides/templated-metadata-values.md
@@ -0,0 +1,17 @@
+# Templated values in Labels and Annotations
+
+Templated values are placeholders in your configuration that get replaced with actual data when the CR is processed. Below is a list of currently supported templated values, their descriptions, and where they can be used.
+
+## Supported templated values
+
+- `"{{ TENANT.USERNAME }}"`
+    - **Description**: The username associated with users specified in [Tenant](../tutorials/tenant/create-tenant.md) under `Owners` and `Editors`.
+    - **Supported in CRs**:
+        - `Tenant`: Under `sandboxMetadata.labels` and `sandboxMetadata.annotations`.
+        - `IntegrationConfig`: Under `metadata.sandboxs.labels` and `metadata.sandboxs.annotations`.
+    - **Example**:
+
+      ```yaml
+        annotation:
+          che.eclipse.org/username: "{{ TENANT.USERNAME }}" # double quotes are required
+      ```
diff --git a/content/tutorials/dev-workspace/enabling-openshift-dev-workspace.md b/content/tutorials/dev-workspace/enabling-openshift-dev-workspace.md
@@ -0,0 +1,118 @@
+# Enabling DevWorkspace for Tenant's sandbox in OpenShift
+
+## DevWorkspaces metadata via Multi Tenant Operator
+
+DevWorkspaces require specific metadata on a namespace for it to work in it. With Multi Tenant Operator (MTO), you can create sandbox namespaces for users of a Tenant, and then add the required metadata automatically on all sandboxes.
+
+## Required metadata for enabling DevWorkspace on sandbox
+
+```yaml
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: workspaces-namespace
+  annotations:
+    che.eclipse.org/username: <username>
+```
+
+## Automate sandbox metadata for all Tenant users via Tenant CR
+
+With Multi Tenant Operator (MTO), you can set `sandboxMetadata` like below to automate metadata for all sandboxes:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1beta2
+kind: Tenant
+metadata:
+  name: bluesky
+spec:
+  owners:
+    users:
+    - [email protected]
+  editors:
+    users:
+    - [email protected]
+  viewers:
+    users:
+    - [email protected]
+  quota: small
+  sandboxConfig:
+    enabled: true
+    private: false
+
+  sandboxMetadata:
+    labels:
+      app.kubernetes.io/part-of: che.eclipse.org
+      app.kubernetes.io/component: workspaces-namespace
+    annotations:
+      che.eclipse.org/username: "{{ TENANT.USERNAME }}"
+```
+
+It will create sandbox namespaces and also apply the `sandboxMetadata` for owners and editors. Notice the template `{{ TENANT.USERNAME }}`, it will resolve the username as value of the corresponding annotation. For more info on templated value, see [here](../../reference-guides/templated-metadata-values.md)
+
+## Automate sandbox metadata for all Tenant users via IntegrationConfig CR
+
+You can also automate the metadata on all sandbox namespaces by using IntegrationConfig, notice `metadata.sandboxes`:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1beta1
+kind: IntegrationConfig
+metadata:
+  name: tenant-operator-config
+  namespace: multi-tenant-operator
+spec:
+  accessControl:
+    namespaceAccessPolicy:
+      deny:
+        privilegedNamespaces: {}
+    privileged:
+      namespaces:
+      - ^default$
+      - ^openshift-*
+      - ^kube-*
+      serviceAccounts:
+      - ^system:serviceaccount:openshift-*
+      - ^system:serviceaccount:kube-*
+      - ^system:serviceaccount:stakater-actions-runner-controller:actions-runner-controller-runner-deployment$
+    rbac:
+      tenantRoles:
+        default:
+          editor:
+            clusterRoles:
+            - edit
+          owner:
+            clusterRoles:
+            - admin
+          viewer:
+            clusterRoles:
+            - view
+  components:
+    console: false
+    ingress:
+      console: {}
+      gateway: {}
+      keycloak: {}
+    showback: false
+  integrations:
+    vault:
+      accessInfo:
+        accessorPath: ""
+        address: ""
+        roleName: ""
+        secretRef:
+          name: ""
+          namespace: ""
+      authMethod: kubernetes
+      config:
+        ssoClient: ""
+      enabled: false
+  metadata:
+    groups: {}
+    namespaces: {}
+    sandboxes:
+      labels:
+        app.kubernetes.io/part-of: che.eclipse.org
+        app.kubernetes.io/component: workspaces-namespace
+      annotations:
+        che.eclipse.org/username: "{{ TENANT.USERNAME }}"
+```
+
+ For more info on templated value `"{{ TENANT.USERNAME }}"`, see [here](../../reference-guides/templated-metadata-values.md)
diff --git a/content/tutorials/tenant/assigning-metadata.md b/content/tutorials/tenant/assigning-metadata.md
@@ -1,6 +1,8 @@
-# Assigning Common/Specific Metadata
+# Assigning metadata
 
-## Distributing common labels and annotations to tenant namespaces via Tenant Custom Resource
+## Assigning Common/Specific Metadata
+
+### Distributing common labels and annotations to tenant namespaces via Tenant Custom Resource
 
 Bill now wants to add labels/annotations to all the namespaces for a tenant. To create those labels/annotations Bill will just add them into `commonMetadata.labels`/`commonMetadata.annotations` field in the tenant CR.
 
@@ -37,7 +39,7 @@ EOF
 
 With the above configuration all tenant namespaces will now contain the mentioned labels and annotations.
 
-## Distributing specific labels and annotations to tenant namespaces via Tenant Custom Resource
+### Distributing specific labels and annotations to tenant namespaces via Tenant Custom Resource
 
 Bill now wants to add labels/annotations to specific namespaces for a tenant. To create those labels/annotations Bill will just add them into `specificMetadata.labels`/`specificMetadata.annotations` and specific namespaces in `specificMetadata.namespaces` field in the tenant CR.
 
@@ -76,3 +78,35 @@ EOF
 ```
 
 With the above configuration all tenant namespaces will now contain the mentioned labels and annotations.
+
+## Assigning metadata to all sandboxes
+
+Bill can choose to apply metadata to sandbox namespaces only by using `sandboxMetadata` property of Tenant CR like below:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1beta2
+kind: Tenant
+metadata:
+  name: bluesky
+spec:
+  owners:
+    users:
+    - [email protected]
+    - [email protected]
+  editors:
+    users:
+    - [email protected]
+    groups:
+    - alpha
+  quota: small
+  sandboxConfig:
+    enabled: true
+    private: true
+  sandboxMetadata: # metadata for all sandbox namespaces
+    labels:
+      app.kubernetes.io/part-of: che.eclipse.org
+    annotations:
+      che.eclipse.org/username: "{{ TENANT.USERNAME }}" # templated placeholder
+```
+
+We are using a templated annotation here. See more on supported templated values for labels and annotations for specific MTO CRs [here](../../reference-guides/templated-metadata-values.md)
diff --git a/content/tutorials/tenant/create-sandbox.md b/content/tutorials/tenant/create-sandbox.md
@@ -84,3 +84,35 @@ kubectl get namespaces
 NAME                             STATUS   AGE
 bluesky-anna-aurora-sandbox      Active   5d5h
 ```
+
+## Set metadata on sandbox namespaces
+
+If you want to have a common metadata on all sandboxes, you can add `sandboxMetadata` to Tenant like below:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1beta2
+kind: Tenant
+metadata:
+  name: bluesky
+spec:
+  owners:
+    users:
+    - [email protected]
+    - [email protected]
+  editors:
+    users:
+    - [email protected]
+    groups:
+    - alpha
+  quota: small
+  sandboxConfig:
+    enabled: true
+    private: true
+  sandboxMetadata:
+    labels:
+      app.kubernetes.io/part-of: che.eclipse.org
+    annotations:
+      che.eclipse.org/username: "{{ TENANT.USERNAME }}" # templated placeholder
+```
+
+Note: In above Tenant, we have used a templated annotation value `"{{ TENANT.USERNAME }}"`. It will resolve to user of the respective sandbox namespace. For more info on it, see [here](../../reference-guides/templated-metadata-values.md)
diff --git a/theme_override/mkdocs.yml b/theme_override/mkdocs.yml
@@ -21,6 +21,8 @@ nav:
         - tutorials/argocd/enabling-multi-tenancy-argocd.md
       - Vault Multi-Tenancy:
         - tutorials/vault/enabling-multi-tenancy-vault.md
+      - Enabling DevWorkspace metadata:
+        - tutorials/dev-workspace/enabling-openshift-dev-workspace.md
     - How-to Guides:
       - how-to-guides/tenant.md
       - how-to-guides/integration-config.md
@@ -45,7 +47,8 @@ nav:
       - reference-guides/secret-distribution.md
       - reference-guides/custom-metrics.md
       - reference-guides/keycloak.md
-      - reference-guides/graph-visualization.md      
+      - reference-guides/graph-visualization.md
+      - reference-guides/templated-metadata-values.md
     - Explanation:
       - explanation/console.md
       - explanation/auth.md