Skip to content

Commit 3d606ab

Browse files
l0rddkwon17
l0rd
authored and
dkwon17
committed
Consolidate DW and DWO configuration under /docs
Signed-off-by: Mario Loriedo <[email protected]>
1 parent 73784d6 commit 3d606ab

File tree

4 files changed

+95
-83
lines changed

4 files changed

+95
-83
lines changed

‎README.md‎

Lines changed: 17 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -26,68 +26,32 @@ Open the IDE:<br/>
2626

2727
## Example
2828

29-
Here is a sample DevWorkspace to provision a Cloud Development Environment for the project
30-
[github.com/l0rd/outyet](https://github.com/l0rd/outyet) with Visual Studio Code as editor and
29+
Here is a sample `DevWorkspace` to provision a Cloud Development Environment for the project
30+
[github.com/l0rd/outyet](https://github.com/l0rd/outyet) with Visual Studio Code as the editor and
3131
`quay.io/devfile/universal-developer-image:ubi8-latest` as the development tooling container image.<br/>
3232

33-
The **template section of a DevWorkspace** is actually [a Devfile](https://devfile.io/docs/2.3.0/what-is-a-devfile): the
34-
`spec.template` schema matches the [Devfile schema](https://devfile.io/docs/2.3.0/devfile-schema).
35-
36-
**Contributions** are extra components that are added on top of the template. Contributions are used to inject editors
37-
such as Visual Studio Code and JetBrains.
38-
3933
![devworkspace](img/devworkspace.png)
4034

41-
## Configuration
42-
43-
### Global configuration for the DevWorkspace Operator
35+
#### DevWorkspace Template
4436

45-
The DevWorkspace Operator installs the DevWorkspaceOperatorConfig custom resource (short name: `dwoc`). To configure global behavior of the DevWorkspace Operator, create a DevWorkspaceOperatorConfig named `devworkspace-operator-config` in the same namespace where the operator is deployed:
46-
```yaml
47-
apiVersion: controller.devfile.io/v1alpha1
48-
kind: DevWorkspaceOperatorConfig
49-
metadata:
50-
name: devworkspace-operator-config
51-
namespace: $OPERATOR_INSTALL_NAMESPACE
52-
config:
53-
# Configuration fields
54-
```
55-
56-
To apply a configuration to specific workspaces instead of globally, an existing DevWorkspaceOperatorConfig can be referenced in a DevWorkspace's attributes:
57-
```yaml
58-
apiVersion: workspace.devfile.io/v1alpha2
59-
kind: DevWorkspace
60-
metadata:
61-
name: my-devworkspace
62-
spec:
63-
template:
64-
attributes:
65-
controller.devfile.io/devworkspace-config:
66-
name: <name of DevWorkspaceOperatorConfig CR>
67-
namespace: <namespace of DevWorkspaceOperatorConfig CR>
68-
```
69-
Configuration specified as above will be merged into the default global configuration, overriding any values present.
37+
The Template section of a `DevWorkspace` is actually [a Devfile](https://devfile.io/docs/2.3.0/what-is-a-devfile): the
38+
`spec.template` schema matches the [Devfile schema](https://devfile.io/docs/2.3.0/devfile-schema). :warning: A few
39+
`Devfile` APIs are
40+
[not supported yet](https://github.com/devfile/devworkspace-operator/blob/main/docs/unsupported-devfile-api.adoc).
7041

71-
To see all all configuration options, see `kubectl explain dwoc.config`, `kubectl explain dwoc.config.workspace`, etc.
42+
#### DevWorkspace Contributions
7243

73-
### Additional configuration
44+
Contributions are extra `Templates` that are added on top of the main `DevWorkspaceTemplate`. Contributions are used to
45+
inject editors such as Visual Studio Code and JetBrains. Contributions are defined as Devfile or DevWorkspace Templates.
46+
Examples are the
47+
[Visual Studio Code devfile](https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-code/latest/devfile.yaml)
48+
and the
49+
[JetBrains IntelliJ devfile](https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/che-incubator/che-idea/latest/devfile.yaml).
7450

75-
DevWorkspaces can be further configured through DevWorkspace attributes and Kubernetes labels/annotations. For a list of all options available, see [additional documentation](docs/additional-configuration.adoc).
51+
#### Additional configuration
7652

77-
### Restricted Access
78-
79-
The `controller.devfile.io/restricted-access` annotation specifies that a DevWorkspace needs additional access control (in addition to RBAC). When a DevWorkspace is created with the `controller.devfile.io/restricted-access` annotation set to `true`, the webhook server will guarantee
80-
- Only the DevWorkspace Operator ServiceAccount or DevWorkspace creator can modify important fields in the DevWorkspace
81-
- Only the DevWorkspace creator can create `pods/exec` into devworkspace-related containers.
82-
83-
This annotation should be used when a DevWorkspace is expected to contain sensitive information that should be protect above the protection provided by standard RBAC rules (e.g. if the DevWorkspace will store the user's OpenShift token in-memory).
84-
85-
Example:
86-
```yaml
87-
metadata:
88-
annotations:
89-
controller.devfile.io/restricted-access: true
90-
```
53+
DevWorkspaces can be further configured through DevWorkspace `attributes`, `labels` and `annotations`. For a list of all
54+
options available, see [additional documentation](docs/additional-configuration.adoc).
9155

9256
## Deploying DevWorkspace Operator
9357

@@ -250,14 +214,6 @@ make generate_all # second commit
250214
```
251215
Example of the devfile API update [PR](https://github.com/devfile/devworkspace-operator/pull/797)
252216

253-
### Controller configuration
254-
255-
Controller behavior can be configured using the `DevWorkspaceOperatorConfig` custom resource (`dwoc` for short). To configure the controller, create a `DevWorkspaceOperatorConfig` named `devworkspace-operator-config` in the same namespace as the controller. If using the Makefile to deploy the DevWorkspaceOperator, a pre-filled config is created automatically (see `deploy/default-config.yaml`).
256-
257-
Configuration settings in the `DevWorkspaceOperatorConfig` override default values found in [pkg/config](https://github.com/devfile/devworkspace-operator/tree/main/pkg/config). The only required configuration setting is `.routing.clusterHostSuffix`, which is required when running on Kubernetes.
258-
259-
To see documentation on configuration settings, including default values, use `kubectl explain` or `oc explain` -- e.g. `kubectl explain dwoc.config.routing.clusterHostSuffix`
260-
261217
### Remove controller from your K8s/OS Cluster
262218
To uninstall the controller and associated CRDs, use the Makefile uninstall rule:
263219
```bash

‎docs/additional-configuration.adoc‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -363,25 +363,3 @@ spec:
363363
----
364364

365365
For documentation on Runtime Classes, see https://kubernetes.io/docs/concepts/containers/runtime-class/
366-
367-
## Configuring the Webhook deployment
368-
The `devworkspace-webhook-server` deployment can be configured in the global DevWorkspaceOperatorConfig (DWOC). The configuration options include: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#replicas[replicas], https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/[pod tolerations] and https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector[nodeSelector].
369-
370-
These configuration options exist in the **global** DWOC's `config.webhook` field:
371-
[source,yaml]
372-
----
373-
apiVersion: controller.devfile.io/v1alpha1
374-
kind: DevWorkspaceOperatorConfig
375-
metadata:
376-
name: devworkspace-operator-config
377-
namespace: $OPERATOR_INSTALL_NAMESPACE
378-
config:
379-
webhook:
380-
nodeSelector: <string, string>
381-
tolerations: <[]tolerations>
382-
replicas: <int32>
383-
----
384-
**Note:** In order for the `devworkspace-webhook-server` configuration options to take effect:
385-
386-
- You must place them in the https://github.com/devfile/devworkspace-operator?tab=readme-ov-file#global-configuration-for-the-devworkspace-operator[global DWOC], which has the name `devworkspace-operator-config` and exists in the namespace where the DevWorkspaceOperator is installed. If it does not already exist on the cluster, you must create it.
387-
- You'll need to terminate the `devworkspace-controller-manager` pod so that the replicaset can recreate it. The new pod will update the `devworkspace-webhook-server` deployment.

‎docs/dwo-configuration.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
## DevWorkspace Operator Configuration
2+
3+
The DevWorkspace Operator installs the `DevWorkspaceOperatorConfig` Custom Resource Definition (short name: `dwoc`).
4+
5+
### Controller configuration
6+
7+
A `DevWorkspaceOperatorConfig` Custom Resource defines the behavior of the DevWorkspace Operator Controller.
8+
9+
To see documentation on configuration settings, including default values, use `kubectl explain` or `oc explain` -- e.g.
10+
`kubectl explain dwoc.config.routing.clusterHostSuffix`.
11+
12+
**The only required configuration setting is `.routing.clusterHostSuffix`, which is required when running on
13+
Kubernetes.**
14+
15+
Configuration settings in the `DevWorkspaceOperatorConfig` override default values found in [pkg/config](https://github.com/devfile/devworkspace-operator/tree/main/pkg/config).
16+
17+
### Global configuration for the DevWorkspace Operator
18+
19+
To configure global behavior of the DevWorkspace Operator, create a `DevWorkspaceOperatorConfig` named
20+
`devworkspace-operator-config` in the same namespace where the operator is deployed:
21+
```yaml
22+
apiVersion: controller.devfile.io/v1alpha1
23+
kind: DevWorkspaceOperatorConfig
24+
metadata:
25+
name: devworkspace-operator-config
26+
namespace: $OPERATOR_INSTALL_NAMESPACE
27+
config:
28+
# Configuration fields
29+
```
30+
31+
### DevWorkspace specific configuration
32+
33+
To apply a configuration to a specific `DevWorkspace` instead of globally, an existing `DevWorkspaceOperatorConfig` can
34+
be referenced in a `DevWorkspace`'s attributes:
35+
```yaml
36+
apiVersion: workspace.devfile.io/v1alpha2
37+
kind: DevWorkspace
38+
metadata:
39+
name: my-devworkspace
40+
spec:
41+
template:
42+
attributes:
43+
controller.devfile.io/devworkspace-config:
44+
name: <name of DevWorkspaceOperatorConfig CR>
45+
namespace: <namespace of DevWorkspaceOperatorConfig CR>
46+
```
47+
Configuration specified as above will be merged into the default global configuration, overriding any values present.
48+
49+
## Configuring the Webhook deployment
50+
The `devworkspace-webhook-server` deployment can be configured in the global `DevWorkspaceOperatorConfig`.
51+
The configuration options include:
52+
[replicas](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#replicas),
53+
[pod tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) and
54+
[nodeSelector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector).
55+
56+
These configuration options exist in the **global** DWOC's `config.webhook` field:
57+
58+
```yaml
59+
apiVersion: controller.devfile.io/v1alpha1
60+
kind: DevWorkspaceOperatorConfig
61+
metadata:
62+
name: devworkspace-operator-config
63+
namespace: $OPERATOR_INSTALL_NAMESPACE
64+
config:
65+
webhook:
66+
nodeSelector: <string, string>
67+
tolerations: <[]tolerations>
68+
replicas: <int32>
69+
```
70+
71+
**Note:** In order for the `devworkspace-webhook-server` configuration options to take effect:
72+
73+
- You must place them in the
74+
[Global configuration for the DevWorkspace Operator](#global-configuration-for-the-devworkspace-operator), which has the
75+
name `devworkspace-operator-config` and exists in the namespace where the DevWorkspaceOperator is installed. If it does
76+
not already exist on the cluster, you must create it.
77+
- You'll need to terminate the `devworkspace-controller-manager` pod so that the replicaset can recreate it. The new pod
78+
will update the `devworkspace-webhook-server` deployment.

‎img/devworkspace.png‎

1.44 KB
Loading

0 commit comments

Comments
 (0)