diff --git a/.vale.ini b/.vale.ini index b244259e..df0ed594 100644 --- 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 index 99fc6933..fb824187 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ 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 @@ -10,8 +9,8 @@ SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is ba 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,42 +56,44 @@ 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 @@ -100,5 +101,5 @@ $ vale content Install [Tilt](https://docs.tilt.dev/index.html), then run: ```bash -$ tilt up -``` \ No newline at end of file +tilt up +``` diff --git a/content/how-to-guides/tenant.md b/content/how-to-guides/tenant.md index ddb906da..2951c9e5 100644 --- 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 new file mode 100644 index 00000000..118f104b --- /dev/null +++ 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 new file mode 100644 index 00000000..bc55f3ed --- /dev/null +++ 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: +``` + +## 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: + - anna@acme.org + editors: + users: + - erik@acme.org + viewers: + users: + - john@acme.org + 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 index f32c10a6..ccdb945f 100644 --- 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: + - anna@aurora.org + - anthony@aurora.org + editors: + users: + - john@aurora.org + 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 index ba874cb3..3a3f8987 100644 --- 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: + - anna@aurora.org + - anthony@aurora.org + editors: + users: + - john@aurora.org + 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 index a3f7f970..ffab05b3 100644 --- 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