From 99df6b6e9ba5f7befe8a1b12674361709a35a387 Mon Sep 17 00:00:00 2001 From: G r e y Date: Tue, 6 Jul 2021 19:35:30 +0000 Subject: [PATCH 1/5] hotfix: Templates language [ch14098] This implements task 2 (documentation) for normalizing the language around workspace templates. Details: * Rename workspaces-as-code directory to workspace-templates * Replace WAC and Workspaces as code with workspace templates --- admin/templates.md | 17 ++--- changelog/1.17.2.md | 6 +- changelog/1.17.3.md | 6 +- changelog/1.18.0.md | 16 ++--- changelog/1.19.0.md | 12 ++-- changelog/1.20.0.md | 4 +- manifest.json | 6 +- workspaces/getting-started.md | 10 +-- .../code-completion.md | 11 ++-- .../index.md | 13 ++-- .../templates.md | 62 +++++++++---------- 11 files changed, 82 insertions(+), 81 deletions(-) rename workspaces/{workspaces-as-code => workspace-templates}/code-completion.md (74%) rename workspaces/{workspaces-as-code => workspace-templates}/index.md (85%) rename workspaces/{workspaces-as-code => workspace-templates}/templates.md (89%) diff --git a/admin/templates.md b/admin/templates.md index 1f0bb9def..1dfa00ecb 100644 --- a/admin/templates.md +++ b/admin/templates.md @@ -1,22 +1,23 @@ --- title: Templates -description: Learn how to manage your workspaces as code templates. +description: Learn how to manage your workspace templates. --- The **Templates** tab features options that control the behavior of workspace -templates, which are the basis of [workspaces as code](../workspaces/workspaces-as-code/index.md). +templates, which are the basis of +[workspace templates](../workspaces/workspace-templates/index.md). -## Enabling workspaces as code +## Enabling workspace templates -By default, workspaces as code is an opt-in feature. The **Enable using +By default, workspaces templates is an opt-in feature. The **Enable using Workspace Templates** toggle allows you to enable or disable the creation of [workspaces](../workspaces/index.md) using predefined templates located in Git repositories. -To enable workspaces as code, go to **Admin > Templates** and set **Enable using -Workspace Templates** to **On**. +To enable workspace templates, go to **Admin > Templates** and set **Enable +using Workspace Templates** to **On**. -![Toggle workspaces as code](../assets/admin/wac_toggle.png) +![Toggle workspace templates](../assets/admin/wac_toggle.png) ## Template policy @@ -82,7 +83,7 @@ defined by the template policy. The **Embeddable Button** section features a form you can use for generating an embeddable button. This button makes it easy for developers to use your -[workspace template](../workspaces/workspaces-as-code/index.md). +[workspace template](../workspaces/workspace-templates/index.md). To create your button: diff --git a/changelog/1.17.2.md b/changelog/1.17.2.md index 32678df73..96d90d634 100644 --- a/changelog/1.17.2.md +++ b/changelog/1.17.2.md @@ -9,9 +9,9 @@ There are no breaking changes in 1.17.2. ### Features ✨ -- Workspaces as code (**WAC**): Workspaces as code (WAC) brings the - _infrastructure as code_ paradigm to Coder environments. WAC allows you to - define and create new environments using **workspace templates**. +- Workspace templates: Workspace templates brings the _infrastructure as code_ + paradigm to Coder environments by allowing you to define and create new + environments using YAML templates. - web: New page available via **Admin** > **Templates** for creating an embeddable quickstart button. - web: New options available when clicking **New Environment** from the diff --git a/changelog/1.17.3.md b/changelog/1.17.3.md index 31e476995..d14682896 100644 --- a/changelog/1.17.3.md +++ b/changelog/1.17.3.md @@ -10,12 +10,12 @@ description: "Released on 04/09/2021" ### Breaking changes ❗ -- infra: Removed `tolerations` from workspaces as code templates. +- infra: Removed `tolerations` from workspace templates. ### Features ✨ -- web: Added a toggle to enable/disable workspaces as code on the **Manage > - Admin > Templates** page. Disabling workspaces as code has the following +- web: Added a toggle to enable/disable workspace templates on the **Manage > + Admin > Templates** page. Disabling workspace templates has the following impact: - New workspaces cannot be created from a template. - Existing workspaces built from a template will continue to operate and may diff --git a/changelog/1.18.0.md b/changelog/1.18.0.md index c998ca983..31af9ff87 100644 --- a/changelog/1.18.0.md +++ b/changelog/1.18.0.md @@ -11,20 +11,20 @@ description: "Released on 04/21/2021" ### Features ✨ -- web: Added the ability to specify a workspaces as code template filepath other - than the default _coder.yaml_ +- web: Added the ability to specify a workspace templates filepath other than + the default _coder.yaml_ - web: Moved _built-in_ sign-in behind a toggle so that it does not display when OIDC is configured for authentication - web: Updated color scheme on the sign-in page -- web: Added dev URL support in workspaces as code templates -- web: Added admin toggle for workspaces as code feature -- web: Added Bitbucket Server support for workspaces as code +- web: Added dev URL support in workspace templates +- web: Added admin toggle for workspace templates feature +- web: Added Bitbucket Server support for workspace templates - infra: Added `CODER_WP_NAME` environment variable to workspaces - cli: Added ability to cordon and uncordon workspace providers which will allow/disallow new workspaces from being provisioned on a specific provider - cli: Added ability to rename workspace providers - web: Improved error notifications with additional details and resolutions. - Added _Tip_, _Error Type_, and enumerations for workspaces as code errors. + Added _Tip_, _Error Type_, and enumerations for workspace templates errors. - infra: Added a background job to update templates - web: Added a workspace status indicator in the **Switch Workspace** selector - web: Added a tooltip with an error message for workspace status indicators @@ -39,8 +39,8 @@ description: "Released on 04/21/2021" **Open in Coder** buttons - web: Fixed the inability to delete an empty organization while workspaces were awaiting deletion in the background -- web: Improved error messages regarding attempts to import a workspaces as code - template from a repository using an SSH URI +- web: Improved error messages regarding attempts to import a workspace template + from a repository using an SSH URI - infra: Fixed a bug that had allowed updates to be made to workspaces created from local template diff --git a/changelog/1.19.0.md b/changelog/1.19.0.md index 6553edf14..f07405f54 100644 --- a/changelog/1.19.0.md +++ b/changelog/1.19.0.md @@ -8,14 +8,14 @@ description: "Released on 05/19/2021" - infra: Workspace assets created by Coder that were previously located at `/opt/coder`, such as code-server and coder-cli, have been moved to `/var/tmp/coder` -- infra: Workspaces as code templates have been updated from version _0.1_ to - _0.2_. Existing workspaces using version _0.1_ templates can be rebuilt, - but no new workspaces can be created using the old format. -- web: The workspace as code _Open in Coder_ embeddable button flow no longer +- infra: Workspace templates have been updated from version _0.1_ to _0.2_. + Existing workspaces using version _0.1_ templates can be rebuilt, but no new + workspaces can be created using the old format. +- web: The workspace templates _Open in Coder_ embeddable button flow no longer includes a _clone_ step; buttons created from prior versions will still work, but Coder will not clone the project. To automate project cloning, use - [`workspace.configure.start`](../workspaces/workspaces-as-code/templates.md#workspaceconfigurestart) -- web: The embedded form for workspaces as code located at **Manage** > + [`workspace.configure.start`](../workspaces/workspace-templates/templates.md#workspaceconfigurestart) +- web: The embedded form for workspace templates located at **Manage** > **Admin** > **Templates** no longer uses the following fields: **Project Repository URL** and **Project Git Service** diff --git a/changelog/1.20.0.md b/changelog/1.20.0.md index e5c6d3256..784711822 100644 --- a/changelog/1.20.0.md +++ b/changelog/1.20.0.md @@ -14,8 +14,8 @@ There are no breaking changes in 1.20.0. the provided default. - web: Added the `node-selector`, `tolerations`, and `annotations` fields to workspace templates. -- other: Added a new JSON schema for writing Coder workspace as code templates - with code completion and syntax checking. +- other: Added a new JSON schema for writing Coder workspace templates with code + completion and syntax checking. - web: Added a service banner that's displayed to all users of the system. The message can be used with existing messages. It can be dismissed by each user at any point and will not be shown again until there is a new message. diff --git a/manifest.json b/manifest.json index bed2767df..8a138a41b 100644 --- a/manifest.json +++ b/manifest.json @@ -55,13 +55,13 @@ "path": "./workspaces/ssh.md" }, { - "path": "./workspaces/workspaces-as-code/index.md", + "path": "./workspaces/workspace-templates/index.md", "children": [ { - "path": "./workspaces/workspaces-as-code/templates.md" + "path": "./workspaces/workspace-templates/templates.md" }, { - "path": "./workspaces/workspaces-as-code/code-completion.md" + "path": "./workspaces/workspace-templates/code-completion.md" } ] } diff --git a/workspaces/getting-started.md b/workspaces/getting-started.md index 3136550de..be5186e75 100644 --- a/workspaces/getting-started.md +++ b/workspaces/getting-started.md @@ -16,7 +16,7 @@ workspaces. Click the **New Environment** button and choose **Custom Workspace**. > To learn more about creating an environment from templates, see -> [Workspaces as code](workspaces-as-code/index.md). +> [Workspace templates](workspace-templates/index.md). ![Create a workspace](../assets/workspaces/create-workspace.png) @@ -39,10 +39,10 @@ image, and runs custom configuration on startup. Learn about the Coder provides advanced settings that allow you to customize your workspace. -If your Coder deployment has [container-based virtual machines -enabled](../admin/workspace-management/cvms.md), Coder creates your workspace as -a [CVMs](cvms.md) by default (you can opt-out of this setting by unchecking the -**Run as Container-based Virtual Machine** box). +If your Coder deployment has +[container-based virtual machines enabled](../admin/workspace-management/cvms.md), +Coder creates your workspace as a [CVMs](cvms.md) by default (you can opt-out of +this setting by unchecking the **Run as Container-based Virtual Machine** box). You can also specify the resources Coder should allocate. diff --git a/workspaces/workspaces-as-code/code-completion.md b/workspaces/workspace-templates/code-completion.md similarity index 74% rename from workspaces/workspaces-as-code/code-completion.md rename to workspaces/workspace-templates/code-completion.md index 744e06e03..dafd96358 100644 --- a/workspaces/workspaces-as-code/code-completion.md +++ b/workspaces/workspace-templates/code-completion.md @@ -1,6 +1,7 @@ --- title: "Workspace template code completion" -description: "Learn how to use code completion when creating workspace templates." +description: + "Learn how to use code completion when creating workspace templates." state: alpha --- @@ -9,8 +10,8 @@ that enables code completion and syntax checking. ## Requirements -You must have the [YAML extension by Red -Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) +You must have the +[YAML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) installed to use this feature. ## How to use @@ -33,8 +34,8 @@ Some keyboard shortcuts you may find helpful include: - Document outlining (Ctrl + Shift + O) - Auto completion (Ctrl + Space) -See the [YAML extension by Red Hat -docs](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) +See the +[YAML extension by Red Hat docs](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) for additional shortcuts. ![Code Completion Demo](../../assets/wac-intellisense-demo.gif) diff --git a/workspaces/workspaces-as-code/index.md b/workspaces/workspace-templates/index.md similarity index 85% rename from workspaces/workspaces-as-code/index.md rename to workspaces/workspace-templates/index.md index 3e2208633..465f46d05 100644 --- a/workspaces/workspaces-as-code/index.md +++ b/workspaces/workspace-templates/index.md @@ -1,12 +1,11 @@ --- -title: "Workspaces as code" +title: "Workspace templates" description: "Learn how to describe workspace configuration as code." state: alpha --- -Workspaces as code (WAC) brings the _infrastructure as code_ paradigm to Coder -workspaces. WAC allows you to define and create new workspaces using **workspace -templates**. +Workspace templates brings the _infrastructure as code_ paradigm to Coder +workspaces. Templates allow you to define and create new workspaces using YAML. [Workspace templates](./templates.md) are declarative YAML files that describe how to configure workspaces and their supporting infrastructure. Coder supports @@ -21,7 +20,7 @@ files with either the `.yaml` or `.yml` extension. We strongly recommend allowing the Git provider to run a webhook capable of reaching the Coder server for immediate template updates. Otherwise, Coder will -update your WAC templates daily. +update your workspace templates daily. ## Creating a workspace template @@ -33,7 +32,7 @@ in our [syntax guide](templates.md). To create a new workspace using a template, go to **New Workspace** > **Create from Template**. -![Create from template button](../../assets/workspaces/workspaces-as-code/create-from-template.png) +![Create from template button](../../assets/workspaces/workspace-templates/create-from-template.png) When prompted, provide: @@ -46,7 +45,7 @@ When prompted, provide: will be `.coder/coder.yaml`, but if you choose a different path, provide it here -![Create workspace from template](../../assets/workspaces/workspaces-as-code/wac-user-form.png) +![Create workspace from template](../../assets/workspaces/workspace-templates/wac-user-form.png) ## Adding an embeddable button diff --git a/workspaces/workspaces-as-code/templates.md b/workspaces/workspace-templates/templates.md similarity index 89% rename from workspaces/workspaces-as-code/templates.md rename to workspaces/workspace-templates/templates.md index 2ebbaba57..4b7783f27 100644 --- a/workspaces/workspaces-as-code/templates.md +++ b/workspaces/workspace-templates/templates.md @@ -10,12 +10,12 @@ state: alpha > supported. To update your workspace, you **must** update your templates to > version _0.2_. -Workspaces as code (WAC) allows you to define and create new workspaces using +Workspace templates allows you to define and create new workspaces using **workspace templates**. Workspace templates are written in YAML and have a `.yaml` or `.yml` extension. -For assistance with creating your Coder YAML file, you can use the [template -intellisense](code-completion.md) feature. +For assistance with creating your Coder YAML file, you can use the +[template intellisense](code-completion.md) feature. Coder looks for your workspace template at the following path: @@ -23,7 +23,7 @@ Coder looks for your workspace template at the following path: /.coder/.yaml ``` -![Template Location](../../assets/workspaces/workspaces-as-code/wac-location.png) +![Template Location](../../assets/workspaces/workspace-templates/wac-location.png) ## Workspace template sample @@ -195,47 +195,47 @@ Determines whether the workspace should be created as a #### workspace.specs.kubernetes.tolerations.value -Adds [Kubernetes -tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) +Adds +[Kubernetes tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to the workspace pod. ```yaml - tolerations: - value: - - key: example1 - operator: Exists - value: value-1 - effect: NoSchedule - tolerationSeconds: 200 - - key: example-3 - operator: Equal - value: value-2 - effect: PreferNoSchedule - tolerationSeconds: 400 - - key: example-3 - value: value-3 - effect: NoExecute - ``` +tolerations: + value: + - key: example1 + operator: Exists + value: value-1 + effect: NoSchedule + tolerationSeconds: 200 + - key: example-3 + operator: Equal + value: value-2 + effect: PreferNoSchedule + tolerationSeconds: 400 + - key: example-3 + value: value-3 + effect: NoExecute +``` `tolerations` is disabled by default and must be enabled by a site admin. #### workspace.specs.kubernetes.node-selector.value -Adds [Kubernetes -NodeSelectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) +Adds +[Kubernetes NodeSelectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) to the workspace pod. The value is a sequence of key/value pairs. For example, the following snippet would add two `nodeSelectors` for Kubernetes: `accelerator:nvidia` and `disktype:ssd`. ```yaml - node-selector: - value: - - key: accelerator - value: nvidia - - key: disktype - value: ssd - ``` +node-selector: + value: + - key: accelerator + value: nvidia + - key: disktype + value: ssd +``` `node-selector` is disabled by default and must be enabled by a site admin. From 5ffac104dd44883eb19aec87856af145715de883 Mon Sep 17 00:00:00 2001 From: G r e y Date: Tue, 6 Jul 2021 19:44:40 +0000 Subject: [PATCH 2/5] fixup! hotfix: Templates language [ch14098] --- admin/templates.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/admin/templates.md b/admin/templates.md index 1dfa00ecb..103c38ce3 100644 --- a/admin/templates.md +++ b/admin/templates.md @@ -3,8 +3,7 @@ title: Templates description: Learn how to manage your workspace templates. --- -The **Templates** tab features options that control the behavior of workspace -templates, which are the basis of +The **Templates** tab features options that control the behavior of [workspace templates](../workspaces/workspace-templates/index.md). ## Enabling workspace templates From fcfd3c5de388e43b5e5f6793080558e5cc68fac8 Mon Sep 17 00:00:00 2001 From: G r e y Date: Tue, 6 Jul 2021 19:56:35 +0000 Subject: [PATCH 3/5] fixup! hotfix: Templates language [ch14098] --- .../create-from-template.png | Bin .../wac-location.png | Bin .../wac-user-form.png | Bin 3 files changed, 0 insertions(+), 0 deletions(-) rename assets/workspaces/{workspaces-as-code => workspace-templates}/create-from-template.png (100%) rename assets/workspaces/{workspaces-as-code => workspace-templates}/wac-location.png (100%) rename assets/workspaces/{workspaces-as-code => workspace-templates}/wac-user-form.png (100%) diff --git a/assets/workspaces/workspaces-as-code/create-from-template.png b/assets/workspaces/workspace-templates/create-from-template.png similarity index 100% rename from assets/workspaces/workspaces-as-code/create-from-template.png rename to assets/workspaces/workspace-templates/create-from-template.png diff --git a/assets/workspaces/workspaces-as-code/wac-location.png b/assets/workspaces/workspace-templates/wac-location.png similarity index 100% rename from assets/workspaces/workspaces-as-code/wac-location.png rename to assets/workspaces/workspace-templates/wac-location.png diff --git a/assets/workspaces/workspaces-as-code/wac-user-form.png b/assets/workspaces/workspace-templates/wac-user-form.png similarity index 100% rename from assets/workspaces/workspaces-as-code/wac-user-form.png rename to assets/workspaces/workspace-templates/wac-user-form.png From 1ff66cffbdd6226a04ac9b929a1d8ebdb2050300 Mon Sep 17 00:00:00 2001 From: G r e y Date: Tue, 6 Jul 2021 16:20:33 -0400 Subject: [PATCH 4/5] Update admin/templates.md Co-authored-by: Katie Horne --- admin/templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin/templates.md b/admin/templates.md index 103c38ce3..0c8595674 100644 --- a/admin/templates.md +++ b/admin/templates.md @@ -8,7 +8,7 @@ The **Templates** tab features options that control the behavior of ## Enabling workspace templates -By default, workspaces templates is an opt-in feature. The **Enable using +By default, workspace templates is an opt-in feature. The **Enable using Workspace Templates** toggle allows you to enable or disable the creation of [workspaces](../workspaces/index.md) using predefined templates located in Git repositories. From daf2d199687491427e4d348c91ea8535de7e9545 Mon Sep 17 00:00:00 2001 From: G r e y Date: Tue, 6 Jul 2021 16:20:45 -0400 Subject: [PATCH 5/5] Update workspaces/getting-started.md Co-authored-by: Katie Horne --- workspaces/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workspaces/getting-started.md b/workspaces/getting-started.md index be5186e75..be1820791 100644 --- a/workspaces/getting-started.md +++ b/workspaces/getting-started.md @@ -41,7 +41,7 @@ Coder provides advanced settings that allow you to customize your workspace. If your Coder deployment has [container-based virtual machines enabled](../admin/workspace-management/cvms.md), -Coder creates your workspace as a [CVMs](cvms.md) by default (you can opt-out of +Coder creates your workspace as a [CVM](cvms.md) by default (you can opt-out of this setting by unchecking the **Run as Container-based Virtual Machine** box). You can also specify the resources Coder should allocate.