diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 5b0a9e73d..54390f9de 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -9,10 +9,16 @@ updates: commit-message: prefix: "chore" ignore: - # These actions deliver the latest versions by updating the - # major release tag, so handle updates manually + # These actions deliver the latest versions by updating the major + # release tag, so ignore minor and patch versions - dependency-name: "actions/*" + update-types: + - version-update:semver-minor + - version-update:semver-patch - dependency-name: "marocchino/sticky-pull-request-comment" + update-types: + - version-update:semver-minor + - version-update:semver-patch - package-ecosystem: "npm" directory: "/" @@ -21,7 +27,10 @@ updates: time: "06:00" timezone: "America/Chicago" ignore: + # Ignore major updates to Node.js types, because they need to + # correspond to the Node.js engine version - dependency-name: "@types/node" - versions: ["15.x", "14.x", "13.x"] + update-types: + - version-update:semver-major commit-message: prefix: "chore" diff --git a/admin/devurls.md b/admin/devurls.md index 73f8c602f..cd706800e 100644 --- a/admin/devurls.md +++ b/admin/devurls.md @@ -94,3 +94,17 @@ deployment will be accessible to any authenticated Coder user. The developer, however, can choose to set a stricter permission level (e.g., allowing only those in their organization to use the dev URL). Developers cannot choose a more permissive option. + +## Authentication with apps requiring a single callback URL + +If you're using GitHub credentials to sign in to an application, and your GitHub +OAuth app has the authorization callback URL set to `localhost`, you will need +to work around the fact that GitHub enforces a single callback URL (since each +workspace gets a unique dev URL). + +To do so, you can either: + +- Use SSH tunneling to tunnel the web app to individual developers' `localhost` + instead of dev URLs (this is also an out-of-the-box feature included with VS + Code Remote) +- Use this workaround for [multiple callback sub-URLs](https://stackoverflow.com/questions/35942009/github-oauth-multiple-authorization-callback-url/38194107#38194107) diff --git a/admin/templates.md b/admin/templates.md index 1f0bb9def..0c8595674 100644 --- a/admin/templates.md +++ b/admin/templates.md @@ -1,22 +1,22 @@ --- 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). +The **Templates** tab features options that control the behavior 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, 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. -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 +82,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/admin/workspace-management/cvms.md b/admin/workspace-management/cvms.md index 9a071b75e..9201e6ad7 100644 --- a/admin/workspace-management/cvms.md +++ b/admin/workspace-management/cvms.md @@ -44,11 +44,11 @@ Google, Azure, and Amazon to support CVMs. To use CVMs with GKE, [create a cluster](../../setup/kubernetes/google.md) using the following parameters: -- GKE Master version `>= 1.17` -- `node-version >= 1.17` +- GKE Master version `latest` +- `node-version = "latest"` - `image-type = "UBUNTU"` -You can also provide `latest` instead of specific version numbers. For example: +For example: ```console gcloud beta container clusters create "YOUR_NEW_CLUSTER" \ diff --git a/assets/workspaces/status-chip.png b/assets/workspaces/status-chip.png new file mode 100644 index 000000000..a9008e873 Binary files /dev/null and b/assets/workspaces/status-chip.png differ diff --git a/assets/workspaces/workspace-overview.png b/assets/workspaces/workspace-overview.png new file mode 100644 index 000000000..470e93a00 Binary files /dev/null and b/assets/workspaces/workspace-overview.png differ 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 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/getting-started.md b/getting-started.md new file mode 100644 index 000000000..9bdcd363d --- /dev/null +++ b/getting-started.md @@ -0,0 +1,104 @@ +--- +title: "Getting started" +description: Get started with Coder. +icon: '' +--- + +We’re excited for you to be part of the growing community of Coder users, and we +wanted to provide an onboarding guide to ensure you have a great experience. +Coder’s [documentation is publicly editable](https://github.com/cdr/docs), +so please feel free to contribute and provide feedback as you desire. + +## Setup and deploy Coder + +To get started with Coder, you’ll need to [deploy Coder](./setup/index.md) to a +Kubernetes cluster. We have documentation to help you [create a +cluster](./setup/kubernetes/index.md) if needed. Once you have a cluster, you +can [install Coder via Helm](./setup/installation.md). + +## Configure Coder + +After you deploy Coder, you’ll need to [upload your license +file](./setup/configuration.md) before you can configure the application (you +can get a trial license for free [here](https://coder.com/trial)). Once logged +in, you’ll be able to access the [administration management](./admin/index.md) +menu to set up things such as [access +controls](./admin/access-control/index.md) with OpenID Connect (OIDC), +[create organizations](./admin/organizations.md), and create an OAuth app for +your users to [connect to your Git provider](./admin/git.md). + +At a minimum, you’ll want to ensure you [add a container +registry](./admin/registries/index.md) for your development environments to pull +from, and [import an image](./images/importing.md) with the tools your +developers need. You can [create custom +images](./guides/customization/custom-workspace.md) for your developer +workspaces as well. + +## Provision users + +With some base configuration done, you’ll want to allow your developers to begin +using Coder. You can manually create and invite users, or you can set up OpenID +Connect (OIDC) with [Azure AD](./guides/admin/oidc-azuread.md) or +[Okta](./guides/admin/oidc-okta.md). If you are using another Identity Provider +(IdP), the process should be very similar. With OIDC configured, Coder will +automatically create a user and add them to the [default +organization](./admin/organizations.md) when a developer logs in for the first +time. + +## Automate + +Coder has a [command-line (CLI) tool](./cli/index.md) that you and your +developers may be interested in using to interact with Coder. The CLI is +completely [open-sourced](https://github.com/cdr/coder-cli), and we always +welcome contributions. Additionally, Coder has a [public API](./guides/api.md) +that you can use to automate various tasks through code. + +## Connect local IDEs + +While Coder supports a [variety of IDEs in the +browser](https://coder.com/docs/coder/v1.20/workspaces/editors), such as VSCode +and the JetBrains product suite, some developers may want to use their local +installation of these tools or other IDEs with Coder. By leveraging the [Coder +CLI](./cli/index.md), developers will be able to [connect their +terminal](./cli/remote-terminal.md) to the remote environment’s terminal, and +enable [file sync](./cli/file-sync.md) to have their local directory’s tree sync +with the remote file system. + +## Maintain and update + +Coder maintains a public [changelog](./changelog/index.md) and [release +calendar](https://coder.com/release-calendar.ical) to help you stay in the know +on features, bug fixes, security updates, and breaking changes that are coming. +Coder releases are available on the third Wednesday of each month, and patch +releases are published and available as needed. + +## Interact with Support + +Coder’s standard support is included with your license. You can reach us at +[support@coder.com](mailto:support@coder.com), and one of our engineers will be +able to assist. Please include any relevant logs, error messages, or +screenshots. + +Coder also has a [public community Slack](https://cdr.co/join-community) you can +join if you’d like. + +Finally, Coder offers premium support through Coder Escalation Services, which +provides a faster response Service-Level Agreement (SLA). Speak to your account +executive if you’re interested in this option. + +## Additional information + +There are a variety of ways to follow Coder to stay up-to-date on company +updates, whitepapers, blog posts, and more. + +- [Coder Blog](https://coder.com/blog) +- [Videos about Coder](https://coder.com/resources/videos) +- [Whitepapers](https://coder.com/resources/whitepapers) +- Social media accounts such as + [LinkedIn](https://www.linkedin.com/company/coderhq), + [YouTube](https://www.youtube.com/channel/UCWexK_ECcUU3vEIdb-VYkfw), + [Twitter](https://twitter.com/coderhq), and others + +Finally, we encourage you to look through the various +[Guides](./guides/index.md) in our public documentation, as it contains more +detailed information on specific use cases and topics. diff --git a/guides/ssl-certificates/cloudflare.md b/guides/ssl-certificates/cloudflare.md index f94a83cda..37d0a1100 100644 --- a/guides/ssl-certificates/cloudflare.md +++ b/guides/ssl-certificates/cloudflare.md @@ -22,18 +22,14 @@ you can enable HTTPS on your Coder deployment. You must have: -- A Kubernetes cluster (v1.15 or greater) with internet connectivity +- A Kubernetes cluster [meeting Coder's + requirements](../../setup/kubernetes/index.md) with internet connectivity - kubectl with patch version [greater than v1.18.8, v1.17.11, or v1.16.14](https://cert-manager.io/docs/installation/upgrading/upgrading-0.15-0.16/#issue-with-older-versions-of-kubectl) ## Step 1: Add cert-manager to your Kubernetes cluster ```console -# Kubernetes 1.16+ -$ kubectl apply --validate=false -f \ -https://github.com/jetstack/cert-manager/releases/download/v1.0.1/cert-manager.yaml - -# Kubernetes <1.16 $ kubectl apply --validate=false -f \ https://github.com/jetstack/cert-manager/releases/download/v1.0.1/cert-manager-legacy.yaml ``` diff --git a/guides/ssl-certificates/route53.md b/guides/ssl-certificates/route53.md index 3f9067e7c..c4133d4bc 100644 --- a/guides/ssl-certificates/route53.md +++ b/guides/ssl-certificates/route53.md @@ -23,8 +23,8 @@ configure your Coder hostname and dev URLs. You must have: -- A [Kubernetes cluster](../../setup/kubernetes/index.md) (v1.17 or greater) - with internet connectivity +- A Kubernetes cluster [meeting Coder's + requirements](../../setup/kubernetes/index.md) with internet connectivity - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) You should also: diff --git a/images/configure.md b/images/configure.md index 490c9c4de..90f749a77 100644 --- a/images/configure.md +++ b/images/configure.md @@ -20,11 +20,18 @@ contained. The following steps will show you how to create and use a config file. -## Step 1: Create the config file +## Step 1: Create the configure file -Using the text editor of your choice, create a file named `configure` and add -the instructions that you want included. For example, the following file shows -how you can clone a repo at build time: +Using the text editor of your choice, create a file named `configure` and make +it executable: + +```console +touch configure +chmod +x configure +``` + +Next, add the instructions that you want included. For example, the following +file shows how you can clone a repo at build time: ```console #!/bin/bash diff --git a/manifest.json b/manifest.json index 38b999266..1e5ef6ed7 100644 --- a/manifest.json +++ b/manifest.json @@ -15,6 +15,9 @@ } ] }, + { + "path": "getting-started.md" + }, { "path": "./workspaces/index.md", "children": [ @@ -55,13 +58,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" } ] } @@ -139,6 +142,9 @@ }, { "path": "./setup/kubernetes/google.md" + }, + { + "path": "./setup/kubernetes/openshift.md" } ] }, diff --git a/package.json b/package.json index c7cf5af76..45f3bba44 100644 --- a/package.json +++ b/package.json @@ -15,11 +15,11 @@ "lint:fix": "markdownlint --config .markdownlint.jsonc --rules .markdownlint-rules --fix '**/*.md'" }, "devDependencies": { - "@types/minimist": "^1.2.1", - "@types/node": "^12.20.15", + "@types/minimist": "^1.2.2", + "@types/node": "^12.20.16", "@types/semver-compare": "^1.0.1", "all-contributors-cli": "^6.20.0", - "husky": "^7.0.0", + "husky": "^7.0.1", "lint-staged": "^11.0.0", "markdownlint-cli": "^0.27.1", "minimist": "^1.2.5", diff --git a/setup/kubernetes/aws.md b/setup/kubernetes/aws.md index a58412247..b00ef13a9 100644 --- a/setup/kubernetes/aws.md +++ b/setup/kubernetes/aws.md @@ -84,13 +84,14 @@ SSH_KEY_PATH=".pub" REGION="YOUR_REGION" ``` -The following will spin up a Kubernetes cluster using `eksctl`: +The following will spin up a Kubernetes cluster using `eksctl` (be sure to +update the parameters as necessary, especially the version number): ```console eksctl create cluster \ --name "$CLUSTER_NAME" \ - --version 1.17 \ + --version \ --region "$REGION" \ --nodegroup-name standard-workers \ --node-type t3.medium \ @@ -172,7 +173,7 @@ as a workspace deployment option, you'll need to kind: ClusterConfig metadata: - version: "1.17" + version: " region: diff --git a/setup/kubernetes/index.md b/setup/kubernetes/index.md index 753669b3d..1daffa008 100644 --- a/setup/kubernetes/index.md +++ b/setup/kubernetes/index.md @@ -1,13 +1,35 @@ --- title: Kubernetes -description: Learn how to set up a K8 cluster for your Coder deployment. +description: Learn how to set up a Kubernetes cluster for your Coder deployment. --- -You can install and deploy Coder onto any Kubernetes cluster (version 1.13.7+) -that meets the [requirements](../requirements.md). +This section contains guides for creating a compatible cluster on common cloud +platforms, including Microsoft Azure, Google Cloud Platform, and Amazon Web +Services. If you already have a Kubernetes cluster, you may wish to proceed to +the [installation guide]. -To help you get up and running, Coder offers the following deployment guides (if -you're already set up with a Kubernetes cluster, please proceed to -[installation](../installation.md)): +## Supported Kubernetes versions + +You can deploy Coder to any [compatible Kubernetes cluster]. Coder follows the +[Kubernetes upstream version support policy], and the latest stable release +version of Coder supports the previous two minor releases as well as the current +release of Kubernetes at time of publication. + +Coder may run successfully with +older versions of Kubernetes. However, we strongly recommend running one of the +currently-supported versions so that you receive applicable fixes, including +security updates, from the Kubernetes project maintainers. + +Coder continuously removes usage of deprecated Kubernetes API versions once +the minimum baseline version of Kubernetes supports the necessary features in +a stable version. We follow this policy to ensure that Coder stops +using deprecated features before they are removed from new versions of +Kubernetes. + +[compatible kubernetes cluster]: ../requirements.md +[kubernetes upstream version support policy]: + https://kubernetes.io/docs/setup/release/version-skew-policy/ + +[installation guide]: ../installation.md diff --git a/setup/kubernetes/k3s.md b/setup/kubernetes/k3s.md index ab88e9be9..677b7b973 100644 --- a/setup/kubernetes/k3s.md +++ b/setup/kubernetes/k3s.md @@ -86,7 +86,7 @@ Traefik in favor of Calico and nginx-ingress. networking and policy enforcement): ```console - kubectl create -f https://docs projectcalico.org/manifests tigera-operator.yaml + kubectl create -f https://docs.projectcalico.org/manifests/tigera-operator.yaml kubectl create -f https://docs.projectcalico.org/manifests/custom-resources.yaml ``` @@ -102,7 +102,7 @@ Traefik in favor of Calico and nginx-ingress. Modify Calico to enable IP forwarding, which is needed for container networking. ```console -vim /etc/cni/net.d/10-canal.conflist +vim /etc/cni/net.d/10-calico.conflist kubectl edit cm cni-config -n calico-system ``` diff --git a/setup/kubernetes/openshift.md b/setup/kubernetes/openshift.md new file mode 100644 index 000000000..4e1522c4b --- /dev/null +++ b/setup/kubernetes/openshift.md @@ -0,0 +1,175 @@ +--- +title: "Red Hat OpenShift" +description: Learn about deploying Coder in OpenShift Container Platform +--- + +This deployment guide shows you how to customize your [OpenShift Container +Platform] cluster to deploy Coder. + +The OpenShift Container Platform includes security features, notably the +restricted [Security Context Constraint] (SCC), that can interfere with Coder. +This guide describes the customizations to the OpenShift cluster and Coder that +ensure an optimal user experience. + +[OpenShift Container Platform]: https://www.openshift.com/products/container-platform +[Security Context Constraint]: https://docs.openshift.com/container-platform/4.7/authentication/managing-security-context-constraints.html + +## Prerequisites + +- An OpenShift cluster with a project (Kubernetes namespace) for Coder +- OpenShift command-line tools (`oc` and `kubectl`) installed + +## Step 1: Modify pod and container security contexts + +OpenShift's SCC feature enforces the settings with which applications must run. +The default SCC setting, `restricted`, requires applications to run as a user +within a project-specific range (`MustRunAsRange`) and does not allow apps to +define a seccomp profile. + +You can view the restrictions using `oc describe scc restricted`: + +```console +$ oc describe scc restricted +Name: restricted +Priority: +Access: + Users: + Groups: system:authenticated +Settings: + Allow Privileged: false + Allow Privilege Escalation: true + Default Add Capabilities: + Required Drop Capabilities: KILL,MKNOD,SETUID,SETGID + Allowed Capabilities: + Allowed Seccomp Profiles: + Allowed Volume Types: configMap,downwardAPI,emptyDir,persistentVolumeClaim,projected,secret + Allowed Flexvolumes: + Allowed Unsafe Sysctls: + Forbidden Sysctls: + Allow Host Network: false + Allow Host Ports: false + Allow Host PID: false + Allow Host IPC: false + Read Only Root Filesystem: false + Run As User Strategy: MustRunAsRange + UID: + UID Range Min: + UID Range Max: + SELinux Context Strategy: MustRunAs + User: + Role: + Type: + Level: + FSGroup Strategy: MustRunAs + Ranges: + Supplemental Groups Strategy: RunAsAny + Ranges: +``` + +You can override the default settings by defining the following in your [Helm +chart](../../guides/admin/helm-charts.md): + +```yaml +coderd: + podSecurityContext: + runAsUser: null + seccompProfile: null + securityContext: + seccompProfile: null +``` + +At this point, you need to get your Coder workspaces running with the +appropriate service account/user. There are two options available to you: + +1. Adding the environment's service account to `anyuid` or `nonroot` +1. Building images compatible with OpenShift + +## Option 1: Add the environment's service account to anyuid or nonroot + +Coder's default base images for workspaces, such as `enterprise-base`, run as +the `coder` user (UID 1000). However, OpenShift doesn't allow this, since +service accounts are required by the `restricted` Security +Context Constraint (SCC) to run with a +project-specific UID. + +To work around this, we we recommend adding this service account to the `anyuid` +or `nonroot` SCC since Coder creates workspaces in pods with the service account +`environments`: + +```console +$ oc adm policy add-scc-to-user nonroot -z environments +clusterrole.rbac.authorization.k8s.io/system:openshift:scc:nonroot added: "environments" + +$ oc adm policy who-can use scc nonroot +resourceaccessreviewresponse.authorization.openshift.io/ + +Namespace: coder +Verb: use +Resource: securitycontextconstraints.security.openshift.io + +Users: system:admin + system:serviceaccount:coder:environment +``` + +## Option 2: Build images compatible with OpenShift + +To run Coder workspaces without modifying Security Context Constraints (SCC), +you can modify the user and permissions in the base images. First, determine +the UID range for the project using: + +```console +$ oc describe project coderName: coder +Created: 10 days ago +Labels: +Annotations: openshift.io/description= + openshift.io/display-name= + openshift.io/requester=kube:admin + openshift.io/sa.scc.mcs=s0:c26,c10 + openshift.io/sa.scc.supplemental-groups=1000670000/10000 + openshift.io/sa.scc.uid-range=1000670000/10000 +Display Name: +Description: +Status: Active +Node Selector: +Quota: +Resource limits: +``` + +Next, create a `BuildConfig` that outputs an image with a UID in the given range +(in this case, `sa.scc.uid-range` begins with `1000670000`): + +```yaml +kind: BuildConfig +apiVersion: build.openshift.io/v1 +metadata: + name: example + namespace: coder +spec: + triggers: + - type: ConfigChange + runPolicy: Serial + source: + type: Dockerfile + dockerfile: | + FROM docker.io/codercom/enterprise-base:ubuntu + + # Switch to root + USER root + + # As root, change the coder user id + RUN usermod --uid=1000670000 coder + + # Go back to the user 'coder' + USER coder + strategy: + type: Docker + dockerStrategy: + imageOptimizationPolicy: SkipLayers + output: + to: + kind: ImageStreamTag + name: 'enterprise-base:latest' +``` + +When creating workspaces, [configure Coder to connect to the internal OpenShift +registry](../../admin/registries/index.md) and use the base image you just created. diff --git a/workspaces/getting-started.md b/workspaces/getting-started.md index 3136550de..d8d80e9c6 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) @@ -31,18 +31,39 @@ Coder redirects you to an overview page for your workspace during the build process. Learn more about the workspace [creation parameters](./workspace-params.md). -Your workspace persists in the home directory, updates to new versions of the -image, and runs custom configuration on startup. Learn about the -[workspace lifecycle](lifecycle.md). +![Workspace overview](../assets/workspaces/workspace-overview.png) + +Your workspace persists in the home directory, updates itself to new versions of +the image on which it is built, and runs custom configuration on startup. Learn +about the [workspace lifecycle](lifecycle.md). + +### Workspace status + +The workspace overview page displays information regarding the status and +performance of your workspace. + +![Workspace overview](../assets/workspaces/status-chip.png) + +The following workspace statuses are available: + +- **Running**: Your workspace is running +- **Off**: Your workspace has been shut off either manually or due to inactivity +- **Error**: An unknown error has occurred +- **Building**: Your workspace is building +- **Turning off**: Your workspace is turning off +- **Unknown**: Your workspace is in an unknown state +- **Initializing**: The container is initializing +- **Decommissioned**: Your workspace is being deleted, and compute resources are + being released. ### Advanced 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 [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. 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. diff --git a/yarn.lock b/yarn.lock index 409b8785a..4f1636403 100644 --- a/yarn.lock +++ b/yarn.lock @@ -50,15 +50,15 @@ resolved "https://registry.yarnpkg.com/@tsconfig/node16/-/node16-1.0.1.tgz#a6ca6a9a0ff366af433f42f5f0e124794ff6b8f1" integrity sha512-FTgBI767POY/lKNDNbIzgAX6miIDBs6NTCbdlDb8TrWovHsSvaVIZDlTqym29C6UqhzwcJx4CYr+AlrMywA0cA== -"@types/minimist@^1.2.1": - version "1.2.1" - resolved "https://registry.yarnpkg.com/@types/minimist/-/minimist-1.2.1.tgz#283f669ff76d7b8260df8ab7a4262cc83d988256" - integrity sha512-fZQQafSREFyuZcdWFAExYjBiCL7AUCdgsk80iO0q4yihYYdcIiH28CcuPTGFgLOCC8RlW49GSQxdHwZP+I7CNg== +"@types/minimist@^1.2.2": + version "1.2.2" + resolved "https://registry.yarnpkg.com/@types/minimist/-/minimist-1.2.2.tgz#ee771e2ba4b3dc5b372935d549fd9617bf345b8c" + integrity sha512-jhuKLIRrhvCPLqwPcx6INqmKeiA5EWrsCOPhrlFSrbrmU4ZMPjj5Ul/oLCMDO98XRUIwVm78xICz4EPCektzeQ== -"@types/node@^12.20.15": - version "12.20.15" - resolved "https://registry.yarnpkg.com/@types/node/-/node-12.20.15.tgz#10ee6a6a3f971966fddfa3f6e89ef7a73ec622df" - integrity sha512-F6S4Chv4JicJmyrwlDkxUdGNSplsQdGwp1A0AJloEVDirWdZOAiRHhovDlsFkKUrquUXhz1imJhXHsf59auyAg== +"@types/node@^12.20.16": + version "12.20.16" + resolved "https://registry.yarnpkg.com/@types/node/-/node-12.20.16.tgz#1acf34f6456208f495dac0434dd540488d17f991" + integrity sha512-6CLxw83vQf6DKqXxMPwl8qpF8I7THFZuIwLt4TnNsumxkp1VsRZWT8txQxncT/Rl2UojTsFzWgDG4FRMwafrlA== "@types/parse-json@^4.0.0": version "4.0.0" @@ -459,10 +459,10 @@ human-signals@^2.1.0: resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-2.1.0.tgz#dc91fcba42e4d06e4abaed33b3e7a3c02f514ea0" integrity sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw== -husky@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/husky/-/husky-7.0.0.tgz#3dbd5d28e76234689ee29bb41e048f28e3e46616" - integrity sha512-xK7lO0EtSzfFPiw+oQncQVy/XqV7UVVjxBByc+Iv5iK3yhW9boDoWgvZy3OGo48QKg/hUtZkzz0hi2HXa0kn7w== +husky@^7.0.1: + version "7.0.1" + resolved "https://registry.yarnpkg.com/husky/-/husky-7.0.1.tgz#579f4180b5da4520263e8713cc832942b48e1f1c" + integrity sha512-gceRaITVZ+cJH9sNHqx5tFwbzlLCVxtVZcusME8JYQ8Edy5mpGDOqD8QBCdMhpyo9a+JXddnujQ4rpY2Ff9SJA== iconv-lite@^0.4.24: version "0.4.24"