From eab1dbedc54f19f5333cbf841a78b1ba223ce021 Mon Sep 17 00:00:00 2001 From: Mike Terhar Date: Sat, 3 Apr 2021 03:29:57 +0000 Subject: [PATCH 01/16] draft of updated air-gapped readme --- setup/air-gapped.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/setup/air-gapped.md b/setup/air-gapped.md index 719c86aa9..6a6737fb1 100644 --- a/setup/air-gapped.md +++ b/setup/air-gapped.md @@ -18,12 +18,21 @@ To do so, you must: ## Dependencies -Before proceeding, please ensure that you've installed the following +Before proceeding, please ensure that you've installed the following software dependencies: - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - [helm](https://helm.sh/docs/intro/install/) +In the same network as the Kubernetes cluster that will run Coder, additional +services need to be configured. Links go to suggestions but many other options +can be used. + +- [Docker registry](https://hub.docker.com/_/registry) +- [DNS server](https://coredns.io) or [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) patched in +- [Certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) + or [self-signed certificates](#) + ## Step 1: Pull all Coder resources into your air-gapped environment Coder is deployed through [helm](https://helm.sh/docs/intro/install/), and the @@ -54,6 +63,8 @@ platform images are hosted in Coder's Docker Hub repo. [dashboard](https://hub.docker.com/r/coderenvs/dashboard) + [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller) + You can pull each of these images from their `coderenvs/:` registry location using the image's name and Coder version: From 4fa09dc9eeb048344e3e60deb29daab71cc852da Mon Sep 17 00:00:00 2001 From: Mike Terhar Date: Sat, 3 Apr 2021 03:55:58 +0000 Subject: [PATCH 02/16] cleaned up and added more --- setup/air-gapped.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/setup/air-gapped.md b/setup/air-gapped.md index 6a6737fb1..e92882a9b 100644 --- a/setup/air-gapped.md +++ b/setup/air-gapped.md @@ -31,7 +31,7 @@ can be used. - [Docker registry](https://hub.docker.com/_/registry) - [DNS server](https://coredns.io) or [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) patched in - [Certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) - or [self-signed certificates](#) + or [self-signed certificates](#self-signed-certificate-for-the-registry) ## Step 1: Pull all Coder resources into your air-gapped environment @@ -63,8 +63,6 @@ platform images are hosted in Coder's Docker Hub repo. [dashboard](https://hub.docker.com/r/coderenvs/dashboard) - [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller) - You can pull each of these images from their `coderenvs/:` registry location using the image's name and Coder version: @@ -72,6 +70,16 @@ platform images are hosted in Coder's Docker Hub repo. docker pull coderenvs/coder-service: ``` + Additional images may be needed to configure and run workspaces: + + [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller) + + [enterprise-node](https://hub.docker.com/r/codercom/enterprise-node) + + [enterprise-intellij](https://hub.docker.com/r/codercom/enterprise-intellij) + + [ubuntu](https://hub.docker.com/_/ubuntu) as a base image + 1. Tag and push all of the images that you've downloaded in the previous step to your internal registry; this registry must be accessible from your air-gapped environment. For example, to push `coder-service`: From c0ded4655e977b3a9674a2ab4efd8e742ec343aa Mon Sep 17 00:00:00 2001 From: Mike Terhar Date: Sat, 3 Apr 2021 04:09:38 +0000 Subject: [PATCH 03/16] linted --- setup/air-gapped.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/setup/air-gapped.md b/setup/air-gapped.md index e92882a9b..8209bfd4b 100644 --- a/setup/air-gapped.md +++ b/setup/air-gapped.md @@ -24,12 +24,14 @@ dependencies: - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - [helm](https://helm.sh/docs/intro/install/) -In the same network as the Kubernetes cluster that will run Coder, additional -services need to be configured. Links go to suggestions but many other options +In the same network as the Kubernetes cluster that will run Coder, additional +services need to be configured. Links go to suggestions but many other options can be used. - [Docker registry](https://hub.docker.com/_/registry) -- [DNS server](https://coredns.io) or [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) patched in +- [DNS server](https://coredns.io) or + [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) + patched in - [Certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) or [self-signed certificates](#self-signed-certificate-for-the-registry) From 13d7c63772a1dafc3e96ff36294f5a0942762e10 Mon Sep 17 00:00:00 2001 From: Mike Terhar Date: Sat, 3 Apr 2021 14:14:30 -0400 Subject: [PATCH 04/16] Add openvsx to recommendation and image ssl --- setup/air-gapped.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/setup/air-gapped.md b/setup/air-gapped.md index 8209bfd4b..c1df68004 100644 --- a/setup/air-gapped.md +++ b/setup/air-gapped.md @@ -76,12 +76,18 @@ platform images are hosted in Coder's Docker Hub repo. [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller) + [OpenVSX](https://github.com/orgs/eclipse/packages/container/package/openvsx-server) + [enterprise-node](https://hub.docker.com/r/codercom/enterprise-node) [enterprise-intellij](https://hub.docker.com/r/codercom/enterprise-intellij) [ubuntu](https://hub.docker.com/_/ubuntu) as a base image + When building images for the environment with a custom CA, follow the + [docs on adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) + to images. + 1. Tag and push all of the images that you've downloaded in the previous step to your internal registry; this registry must be accessible from your air-gapped environment. For example, to push `coder-service`: From ac774ca27c079673ba939d0821f8794e72558d23 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 7 Apr 2021 09:22:34 -0500 Subject: [PATCH 05/16] Edit text --- setup/air-gapped.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/setup/air-gapped.md b/setup/air-gapped.md index c1df68004..2361d94a9 100644 --- a/setup/air-gapped.md +++ b/setup/air-gapped.md @@ -24,15 +24,15 @@ dependencies: - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - [helm](https://helm.sh/docs/intro/install/) -In the same network as the Kubernetes cluster that will run Coder, additional -services need to be configured. Links go to suggestions but many other options -can be used. - -- [Docker registry](https://hub.docker.com/_/registry) -- [DNS server](https://coredns.io) or - [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) - patched in -- [Certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) +Next, configure the following items in the same network as the Kubernetes +cluster that will run Coder (we've provided links to a suggested option for each +item type, but you're welcome to use the alternatives of your choice): + +- [Docker Registry](https://hub.docker.com/_/registry) +- A [DNS server](https://coredns.io) (or you can use + [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/)) +- A + [certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) or [self-signed certificates](#self-signed-certificate-for-the-registry) ## Step 1: Pull all Coder resources into your air-gapped environment @@ -72,9 +72,12 @@ platform images are hosted in Coder's Docker Hub repo. docker pull coderenvs/coder-service: ``` - Additional images may be needed to configure and run workspaces: + To access Coder, you'll need an ingress controller; you can use + [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller), + or you can use your own. - [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller) + The following images are optional, though you're welcome to take advantage of + Coder's versions instead of building your own: [OpenVSX](https://github.com/orgs/eclipse/packages/container/package/openvsx-server) @@ -82,10 +85,11 @@ platform images are hosted in Coder's Docker Hub repo. [enterprise-intellij](https://hub.docker.com/r/codercom/enterprise-intellij) - [ubuntu](https://hub.docker.com/_/ubuntu) as a base image + [ubuntu](https://hub.docker.com/_/ubuntu) - When building images for the environment with a custom CA, follow the - [docs on adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) + When building images for your environments that rely on a custom certificate + authority, be sure to follow the + [docs for adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) to images. 1. Tag and push all of the images that you've downloaded in the previous step to From 60b25cbb08d6cd5c1929140e14ddb1ffe811dff7 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 7 Apr 2021 11:16:46 -0500 Subject: [PATCH 06/16] Split docs; edit content --- manifest.json | 11 ++ setup/air-gapped/index.md | 171 +++++++++++++++++++++++++++++ setup/air-gapped/infrastructure.md | 159 +++++++++++++++++++++++++++ 3 files changed, 341 insertions(+) create mode 100644 setup/air-gapped/index.md create mode 100644 setup/air-gapped/infrastructure.md diff --git a/manifest.json b/manifest.json index d2860b3a1..94e143bae 100644 --- a/manifest.json +++ b/manifest.json @@ -132,6 +132,7 @@ } ] }, +<<<<<<< HEAD { "path": "./setup/installation.md" }, @@ -147,6 +148,16 @@ { "path": "./setup/updating.md" } +======= + { "path": "./setup/installation.md" }, + { "path": "./setup/configuration.md" }, + { "path": "./setup/licensing.md" }, + { + "path": "./setup/air-gapped/index.md", + "children": [{ "path": "./setup/air-gapped/infrastrucutre.md" }] + }, + { "path": "./setup/updating.md" } +>>>>>>> Split docs; edit content ] }, { diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md new file mode 100644 index 000000000..b61ac5f09 --- /dev/null +++ b/setup/air-gapped/index.md @@ -0,0 +1,171 @@ +--- +title: Air-Gapped Deployment +description: Learn how to set up an air-gapped Coder deployment. +--- + +If you need increased security for your Coder deployments, you can set up an +air-gapped deployment. + +To do so, you must: + +- Pull all Coder deployment resources into your air-gapped environment +- Push the images to your Docker registry, +- Deploy Coder from within your air-gapped environment + +> Coder licenses issued as part of the trial program do not support air-gapped +> deployments. + +## Dependencies + +Before proceeding, please ensure that you've installed the following software +dependencies: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [helm](https://helm.sh/docs/intro/install/) + +Next, configure the following items in the same network as the Kubernetes +cluster that will run Coder (we've provided links to a suggested option for each +item type, but you're welcome to use the alternatives of your choice): + +- [Docker Registry](https://hub.docker.com/_/registry) +- A [DNS server](https://coredns.io) (or you can use + [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/)) +- A + [certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) + or [self-signed certificates](#self-signed-certificate-for-the-registry) + +## Network configuration + +Coder requires several preliminary steps to be performed on your network before +you can deploy Coder. If don't already have the following on your network, +please see our [infrastructure setup guide](infrastructure.md): + +- A certificate authority +- A domain name service +- A local Docker Registry + +## Version controlling your changes to the Coder install files + +Throughout this article, we will suggest changes to the Helm chart that you'll +obtain from the `.tgz` that's returned when you run `helm pull`. We recommend +version controlling your files. + +## Step 1: Pull all Coder resources into your air-gapped environment + +Coder is deployed through [helm](https://helm.sh/docs/intro/install/), and the +platform images are hosted in Coder's Docker Hub repo. + +1. Pull down the Coder helm charts by running the following in a non-air-gapped + environment: + + ```console + helm repo add coder https://helm.coder.com + helm pull coder/coder + ``` + + These commands will add Coder's helm charts and pull the latest stable + release into a tarball file whose name uses the following format: + `coder-X.Y.Z.tgz` (X.Y.Z is the Coder release number). + +1. Pull the images for the Coder platform from the following Docker Hub + locations: + + [coder-service](https://hub.docker.com/r/coderenvs/coder-service) + + [envbox](https://hub.docker.com/r/coderenvs/envbox) + + [envbuilder](https://hub.docker.com/r/coderenvs/envbuilder) + + [timescale](https://hub.docker.com/r/coderenvs/timescale) + + [dashboard](https://hub.docker.com/r/coderenvs/dashboard) + + You can pull each of these images from their `coderenvs/:` + registry location using the image's name and Coder version: + + ```console + docker pull coderenvs/coder-service: + ``` + + To access Coder, you'll need an ingress controller; you can use + [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller), + or you can use your own. + + The following images are optional, though you're welcome to take advantage of + Coder's versions instead of building your own: + + [OpenVSX](https://github.com/orgs/eclipse/packages/container/package/openvsx-server) + + [enterprise-node](https://hub.docker.com/r/codercom/enterprise-node) + + [enterprise-intellij](https://hub.docker.com/r/codercom/enterprise-intellij) + + [ubuntu](https://hub.docker.com/_/ubuntu) + + When building images for your environments that rely on a custom certificate + authority, be sure to follow the + [docs for adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) + to images. + +1. Tag and push all of the images that you've downloaded in the previous step to + your internal registry; this registry must be accessible from your air-gapped + environment. For example, to push `coder-service`: + + ```console + docker tag coderenvs/coder-service: my-registry.com/coderenvs/coder-service: + docker push my-registry.com/coderenvs/coder-service: + ``` + +1. Modify the image used for the ingress controller. In `coder-X.Y.Z.tgz`, which + you obtained by running `helm pull`, find the `templates/ingress.yaml` file. + You'll see that this file has only one instance of `image:`. Replace this + line: + + ```yaml + quay.io/kubernetes-ingress-controller/nginx-ingress-controller: + ``` + + with the image for your local ingress controller image: + + ```yaml + /nginx-ingress-controller: + ``` + +1. Once all of the resources are in your air-gapped network, run the following + to deploy Coder to your Kubernetes cluster: + + ```console + kubectl create namespace coder + helm --namespace coder install coder /path/to/coder-X.Y.Z.tgz \ + --set cemanager.image=my-registry.com/coderenvs/coder-service: \ + --set envproxy.image=my-registry.com/coderenvs/coder-service: \ + --set envbuilder.image=my-registry.com/coderenvs/envbuilder: \ + --set timescale.image=my-registry.com/coderenvs/timescale: \ + --set dashboard.image=my-registry.com/coderenvs/dashboard: \ + --set envbox.image=my-registry.com/coderenvs/envbox: + ``` + + If you'd like to run this command after navigating _into_ the `coder.tgz` + directory, you can replace the `coder.tgz` path with a period: + + ```bash + helm install --wait --atomic --debug --namespace coder coder . \ + --set cemanager.image=$REGISTRY_DOMAIN_NAME/coderenvs/coder-service: \ + --set envproxy.image=$REGISTRY_DOMAIN_NAME/coderenvs/coder-service: \ + --set envbox.image=$REGISTRY_DOMAIN_NAME/coderenvs/envbox: \ + --set envbuilder.image=$REGISTRY_DOMAIN_NAME/coderenvs/envbuilder: \ + --set timescale.image=$REGISTRY_DOMAIN_NAME/coderenvs/timescale: \ + --set dashboard.image=$REGISTRY_DOMAIN_NAME/coderenvs/dashboard: \ + -f registry-cert-values.yml + ``` + +1. Next, follow the [Installation](installation.md) guide beginning with **step + 6** to get the access URL and the temporary admin password, which allows you + to proceed with setting up and configuring Coder. + +## Extensions marketplace + +You can configure your deployment to use the internal, built-in extension +marketplace, allowing your developers to utilize whitelisted IDE extensions +within your air-gapped environment. For additional details, see +[Extensions](../admin/environment-management/extensions.md). diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md new file mode 100644 index 000000000..cd213b913 --- /dev/null +++ b/setup/air-gapped/infrastructure.md @@ -0,0 +1,159 @@ +--- +title: Air-Gapped Network Setup +description: Learn how to set up a network for air-gapped Coder deployment. +--- + +This article will walk you through setting up your network to support an +air-gapped Coder deployment. + +If your network already has the following, you can proceed with your +installation: + +- A certificate authority +- A domain name service +- A local Docker Registry + +> The code snippets provided in this article are sourced from third-party +> software packages. While we attempt to keep this article up-to-date, we +> strongly recommend that you verify the snippets as well before using. + +## Creating the local registry and generating a self-signed certificate + +You will need to create a local registry to store your Coder images and +self-signed certificates (you can use self-signed certificates in any +environment, but they're required for air-gapped deployments). + +You can create your local registry to and your self-signed certificate at the +same time: + +```bash +export REGISTRY_DOMAINNAME=registry.local +mkdir /certs +openssl req \ + -newkey rsa:4096 -nodes -sha256 -keyout /certs/registry.key \ + -x509 -days 365 -out /certs/registry.crt +``` + +The console will prompt you for `Common Name [CN]:`; provide the value that +matches exactly what you set with your DNS. For the volume mounted at +`/var/lib/registry`, make sure that it has at least 10 GB for Coder images. + +Start the registry container that you just created: + +```bash +docker run -d -p 443:5000 \ + -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt \ + -e REGISTRY_HTTP_TLS_KEY=/certs/registry.key \ + -v /certs:/certs \ + -v /var/lib/docker/registry:/var/lib/registry \ + registry:2 +``` + +> For the volume mounted at `/var/lib/registry` make sure it can store 10+ GB +> for just Coder images. + +## Configuring the Kubernetes Node + +Before the Kubernetes node can accept your certificate, you'll need to mark your +`registry.crt` file as trusted. The specific locations where you need to have +this file depends on your Linux distribution and the container runtime: + +```plaintext +/usr/local/share/ca-certificates/registry.crt +/etc/docker/certs.d/${REGISTRY_DOMAIN_NAME}/ca.crt +/etc/ssl/certs/registry.crt +/etc/pki/tls/registry.crt +``` + +If you're working with containerd, use the following to patch in certificates +for images in the local registry domain: + +```console +update-ca-certificates +cat <> /etc/containerd/config.toml +[plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN_NAME".tls] + insecure_skip_verify = true +EOT +systemctl restart containerd +``` + +Because you'll need to run the steps described in this section on all nodes that +will be scheduling Coder images, we recommend that you either: + +1. Include these steps in the image itself +1. Run an init script including these instructions whenever you add a new node + to your cluster + +## Adding certificate secrets to the Helm chart + +Coder validates images and pulls tags using API calls, so issues with your +certificates may prevent you from adding images. If you see such issues and you +have a certificate authority in your network, you may need to add the root +certificate. + +To pass a self-signed certificate to Coder's images, you'll need to: + +1. Create a secret +1. Reference the secret in your Coder Helm chart + +To create a secret, run: + +```console +kubectl -n coder create secret generic local-registry-cert --from-file=/certs +``` + +When using the above command, you're creating the secret from a directory with a +single file. The directory name doesn't matter, but the filename becomes the +secret **key**. + +> If you changed the `-out` argument on the OpenSSL command used to generate the +> certificates, or if you moved the certificates, make sure that you adjust the +> path included with `--from-file=`. + +To verify your secret: + +```console +kubectl -n coder get secret local-registry-cert -o yaml +``` + +You'll need to add your secret to the Helm chart, and you can do this as part of +your verification step. To do so, place the following snippet into a YAML file +named `registry-cert-values.yml`: + +```yaml +certs: + secret: + name: "local-registry-cert" + key: "registry.crt" +``` + +Then, add the flag `-f registry-cert-values.yml` to the end of the secret +verification immediately above: + +```console +kubectl -n coder get secret local-registry-cert -o yaml -f registry-cert-values.yml +``` + +### Resolving the registry using the cluster's DNS or hostAliases + +Your Nodes must have their host file set to the `$REGISTRY_DOMAIN` and the +static IP address of the local registry. For example, if the registry is on +10.0.0.2, then add this to your Node configuration script: + +```console +echo "10.0.0.2 $REGISTRY_DOMAIN_NAME" >> /etc/hosts +``` + +> This modification may not help the containers _within_ the cluster, since +> Kubernetes forwards some of its DNS services out of the cluster. If, at a +> later point, you discover that the hosts file on the node isn't being heeded +> by pods, you can work around this by extracting the Helm chart from +> `coder-X.Y.Z.tgz` and patching the ce-manager deployment (this goes at the +> same indentation level as `containers:`): +> +> ```yaml +> hostAliases: +> - hostnames: +> - $REGISTRY_DOMAIN_NAME +> ip: 10.0.0.2 +> ``` From 5d58bae498b557c4bf3c3931c2cfebcee9410233 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Thu, 8 Apr 2021 11:25:44 -0500 Subject: [PATCH 07/16] Fix ordering --- manifest.json | 2 +- setup/air-gapped/index.md | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/manifest.json b/manifest.json index 94e143bae..3c886e32a 100644 --- a/manifest.json +++ b/manifest.json @@ -154,7 +154,7 @@ { "path": "./setup/licensing.md" }, { "path": "./setup/air-gapped/index.md", - "children": [{ "path": "./setup/air-gapped/infrastrucutre.md" }] + "children": [{ "path": "./setup/air-gapped/infrastructure.md" }] }, { "path": "./setup/updating.md" } >>>>>>> Split docs; edit content diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index b61ac5f09..ca340dcbd 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -76,7 +76,12 @@ platform images are hosted in Coder's Docker Hub repo. [envbuilder](https://hub.docker.com/r/coderenvs/envbuilder) - [timescale](https://hub.docker.com/r/coderenvs/timescale) + [timescale](https://hub.docker.com/r/coderenvs/timescale) (**Note**: We + recommend you only use timescale for evaluation purposes if you don't have an + external PostgreSQL database available. For production environments, we + strong recommend that you use an external PostgreSQL database; the + installation section will cover more on updating your Helm chart with your + database information.) [dashboard](https://hub.docker.com/r/coderenvs/dashboard) From 3fdfb9a251937d9aa6739772a52f6db797701312 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Wed, 7 Apr 2021 12:01:21 -0500 Subject: [PATCH 08/16] clarify timescale usage --- setup/air-gapped/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index ca340dcbd..b9446832d 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -70,6 +70,10 @@ platform images are hosted in Coder's Docker Hub repo. 1. Pull the images for the Coder platform from the following Docker Hub locations: + > Timescale is an internal database meant for evaluation deployments. It is + > not It is not recommended to run this service in production. Connect to an + > external Postgres database for production deployments. + [coder-service](https://hub.docker.com/r/coderenvs/coder-service) [envbox](https://hub.docker.com/r/coderenvs/envbox) From 259850452bdf68ccc5a1097a7c9bf53e77b2e813 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Mon, 12 Apr 2021 14:23:45 -0500 Subject: [PATCH 09/16] Add clarification --- setup/air-gapped/infrastructure.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index cd213b913..08c606e6c 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -56,7 +56,8 @@ docker run -d -p 443:5000 \ Before the Kubernetes node can accept your certificate, you'll need to mark your `registry.crt` file as trusted. The specific locations where you need to have -this file depends on your Linux distribution and the container runtime: +this file depends on your Linux distribution and the container runtime, but here +is a partial list to help you get started: ```plaintext /usr/local/share/ca-certificates/registry.crt From d00523fc00f111637af568472cc1ce5f221e60dc Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Mon, 12 Apr 2021 14:27:15 -0500 Subject: [PATCH 10/16] Fix extensions error --- setup/air-gapped.md | 133 -------------------------------------- setup/air-gapped/index.md | 12 +++- 2 files changed, 9 insertions(+), 136 deletions(-) delete mode 100644 setup/air-gapped.md diff --git a/setup/air-gapped.md b/setup/air-gapped.md deleted file mode 100644 index 2361d94a9..000000000 --- a/setup/air-gapped.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Air-gapped deployment -description: Learn how to set up an air-gapped Coder deployment. ---- - -If you need increased security for your Coder deployments, you can set up an -air-gapped deployment. - -To do so, you must: - -- Pull all Coder deployment resources into your air-gapped environment -- Push the images to your Docker registry, -- Deploy Coder from within your air-gapped environment - -> Coder licenses issued as part of the trial program do not support air-gapped -> deployments. If an air-gapped deployment is a requirement for you, please -> [reach out to our team](https://coder.com/contact) to discuss a pilot. - -## Dependencies - -Before proceeding, please ensure that you've installed the following software -dependencies: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -Next, configure the following items in the same network as the Kubernetes -cluster that will run Coder (we've provided links to a suggested option for each -item type, but you're welcome to use the alternatives of your choice): - -- [Docker Registry](https://hub.docker.com/_/registry) -- A [DNS server](https://coredns.io) (or you can use - [HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/)) -- A - [certificate authority](https://github.com/activecm/docker-ca/blob/master/Dockerfile) - or [self-signed certificates](#self-signed-certificate-for-the-registry) - -## Step 1: Pull all Coder resources into your air-gapped environment - -Coder is deployed through [helm](https://helm.sh/docs/intro/install/), and the -platform images are hosted in Coder's Docker Hub repo. - -1. Pull down the Coder helm charts by running the following in a non-air-gapped - environment: - - ```console - helm repo add coder https://helm.coder.com - helm pull coder/coder - ``` - - These commands will add Coder's helm charts and pull the latest stable - release into a tarball file whose name uses the following format: - coder-X.Y.Z.tgz (X.Y.Z is the Coder release number). - -1. Pull the images for the Coder platform from the following Docker Hub - locations: - - [coder-service](https://hub.docker.com/r/coderenvs/coder-service) - - [envbox](https://hub.docker.com/r/coderenvs/envbox) - - [envbuilder](https://hub.docker.com/r/coderenvs/envbuilder) - - [timescale](https://hub.docker.com/r/coderenvs/timescale) - - [dashboard](https://hub.docker.com/r/coderenvs/dashboard) - - You can pull each of these images from their `coderenvs/:` - registry location using the image's name and Coder version: - - ```console - docker pull coderenvs/coder-service: - ``` - - To access Coder, you'll need an ingress controller; you can use - [nginx-ingress-controller](https://quay.io/kubernetes-ingress-controller/nginx-ingress-controller), - or you can use your own. - - The following images are optional, though you're welcome to take advantage of - Coder's versions instead of building your own: - - [OpenVSX](https://github.com/orgs/eclipse/packages/container/package/openvsx-server) - - [enterprise-node](https://hub.docker.com/r/codercom/enterprise-node) - - [enterprise-intellij](https://hub.docker.com/r/codercom/enterprise-intellij) - - [ubuntu](https://hub.docker.com/_/ubuntu) - - When building images for your environments that rely on a custom certificate - authority, be sure to follow the - [docs for adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) - to images. - -1. Tag and push all of the images that you've downloaded in the previous step to - your internal registry; this registry must be accessible from your air-gapped - environment. For example, to push `coder-service`: - - ```console - docker tag coderenvs/coder-service: my-registry.com/coderenvs/coder-service: - docker push my-registry.com/coderenvs/coder-service: - ``` - -1. Once all of the resources are in your air-gapped network, run the following - to deploy Coder to your Kubernetes cluster: - - ```console - kubectl create namespace coder - helm --namespace coder install coder /path/to/coder-X.Y.Z.tgz \ - --set cemanager.image=my-registry.com/coderenvs/coder-service: \ - --set envproxy.image=my-registry.com/coderenvs/coder-service: \ - --set envbuilder.image=my-registry.com/coderenvs/envbuilder: \ - --set timescale.image=my-registry.com/coderenvs/timescale: \ - --set dashboard.image=my-registry.com/coderenvs/dashboard: \ - --set envbox.image=my-registry.com/coderenvs/envbox: - ``` - -1. Next, follow the [Installation](installation.md) guide beginning with **step - 6** to get the access URL and the temporary admin password, which allows you - to proceed with setting up and configuring Coder. - -## Extensions marketplace - -Coder users in an air-gapped environment cannot access the public VS Code -marketplace. However, you can point Coder to an air-gapped instance of -[OpenVSX](https://github.com/eclipse/openvsx) to serve assets to users. For -instructions on implementing this, see -[Extensions](../admin/environment-management/extensions.md). - -You can also review the [OpenVSX deployment wiki] for more information. - -[openvsx deployment wiki]: - https://github.com/eclipse/openvsx/wiki/Deploying-Open-VSX diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index b9446832d..29732ea34 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -174,7 +174,13 @@ platform images are hosted in Coder's Docker Hub repo. ## Extensions marketplace -You can configure your deployment to use the internal, built-in extension -marketplace, allowing your developers to utilize whitelisted IDE extensions -within your air-gapped environment. For additional details, see +Coder users in an air-gapped environment cannot access the public VS Code +marketplace. However, you can point Coder to an air-gapped instance of +[OpenVSX](https://github.com/eclipse/openvsx) to serve assets to users. For +instructions on implementing this, see [Extensions](../admin/environment-management/extensions.md). + +You can also review the [OpenVSX deployment wiki] for more information. + +[openvsx deployment wiki]: + https://github.com/eclipse/openvsx/wiki/Deploying-Open-VSX From 8d8ea74ea994e1f4b1704cddf31c34e2211abb2a Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Mon, 12 Apr 2021 14:30:34 -0500 Subject: [PATCH 11/16] Fix manifest --- manifest.json | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/manifest.json b/manifest.json index 3c886e32a..cf5d16ca9 100644 --- a/manifest.json +++ b/manifest.json @@ -132,23 +132,6 @@ } ] }, -<<<<<<< HEAD - { - "path": "./setup/installation.md" - }, - { - "path": "./setup/configuration.md" - }, - { - "path": "./setup/licensing.md" - }, - { - "path": "./setup/air-gapped.md" - }, - { - "path": "./setup/updating.md" - } -======= { "path": "./setup/installation.md" }, { "path": "./setup/configuration.md" }, { "path": "./setup/licensing.md" }, @@ -157,7 +140,6 @@ "children": [{ "path": "./setup/air-gapped/infrastructure.md" }] }, { "path": "./setup/updating.md" } ->>>>>>> Split docs; edit content ] }, { From 14861d139c5ee1ef0296dd6407a7975a6f80e690 Mon Sep 17 00:00:00 2001 From: Mike Terhar Date: Mon, 12 Apr 2021 16:09:36 -0400 Subject: [PATCH 12/16] Apply suggestions from code review Reduced second-person and upgraded the tone --- setup/air-gapped/infrastructure.md | 55 +++++++++++++++--------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index 08c606e6c..98dc1369e 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -3,11 +3,10 @@ title: Air-Gapped Network Setup description: Learn how to set up a network for air-gapped Coder deployment. --- -This article will walk you through setting up your network to support an -air-gapped Coder deployment. +This article walks through setting up a the supporting infrastructure for +an air-gapped Coder deployment. -If your network already has the following, you can proceed with your -installation: +If the network already has the following, proceed with [the installation](../air-gapped): - A certificate authority - A domain name service @@ -19,12 +18,12 @@ installation: ## Creating the local registry and generating a self-signed certificate -You will need to create a local registry to store your Coder images and -self-signed certificates (you can use self-signed certificates in any -environment, but they're required for air-gapped deployments). +To operate, Coder needs an image registry to store your Coder images. +Docker's `registry:2` image assumes that HTTPS will be used and supports +self-signed certificates. -You can create your local registry to and your self-signed certificate at the -same time: +Before starting the registry container, create a self-signed certificate at the +with a command like: ```bash export REGISTRY_DOMAINNAME=registry.local @@ -54,10 +53,10 @@ docker run -d -p 443:5000 \ ## Configuring the Kubernetes Node -Before the Kubernetes node can accept your certificate, you'll need to mark your -`registry.crt` file as trusted. The specific locations where you need to have -this file depends on your Linux distribution and the container runtime, but here -is a partial list to help you get started: +Before the Kubernetes node can accept run local images, it needs to consider the new +`registry.crt` file as trusted. The specific locations and methods to store and +trust the certificate vary depending on the Linux distribution and the container +runtime, but here is a partial list to start with: ```plaintext /usr/local/share/ca-certificates/registry.crt @@ -66,7 +65,7 @@ is a partial list to help you get started: /etc/pki/tls/registry.crt ``` -If you're working with containerd, use the following to patch in certificates +If the cluster uses containerd, apply the following to patch in certificates for images in the local registry domain: ```console @@ -78,8 +77,8 @@ EOT systemctl restart containerd ``` -Because you'll need to run the steps described in this section on all nodes that -will be scheduling Coder images, we recommend that you either: +Because the steps described in this section must be run on all nodes which +will be scheduling Coder images, it is best to: 1. Include these steps in the image itself 1. Run an init script including these instructions whenever you add a new node @@ -87,10 +86,10 @@ will be scheduling Coder images, we recommend that you either: ## Adding certificate secrets to the Helm chart -Coder validates images and pulls tags using API calls, so issues with your -certificates may prevent you from adding images. If you see such issues and you -have a certificate authority in your network, you may need to add the root -certificate. +Coder validates images and pulls tags using direct REST API calls to the registry. +Other internal services (OICD, Git providers, etc) which use HTTPS APIs require +the Coder container to trust the certificate. The Coder helm chart can be used to +add a root CA certificate to the Coder service images. To pass a self-signed certificate to Coder's images, you'll need to: @@ -103,7 +102,7 @@ To create a secret, run: kubectl -n coder create secret generic local-registry-cert --from-file=/certs ``` -When using the above command, you're creating the secret from a directory with a +When using the above command, `kubectl` creates the secret from a directory with a single file. The directory name doesn't matter, but the filename becomes the secret **key**. @@ -111,15 +110,14 @@ secret **key**. > certificates, or if you moved the certificates, make sure that you adjust the > path included with `--from-file=`. -To verify your secret: +To verify the new secret: ```console kubectl -n coder get secret local-registry-cert -o yaml ``` -You'll need to add your secret to the Helm chart, and you can do this as part of -your verification step. To do so, place the following snippet into a YAML file -named `registry-cert-values.yml`: +Reference the newly secret from the Helm chart by adding the following +snippet into a YAML file named `registry-cert-values.yml`: ```yaml certs: @@ -137,9 +135,10 @@ kubectl -n coder get secret local-registry-cert -o yaml -f registry-cert-values. ### Resolving the registry using the cluster's DNS or hostAliases -Your Nodes must have their host file set to the `$REGISTRY_DOMAIN` and the -static IP address of the local registry. For example, if the registry is on -10.0.0.2, then add this to your Node configuration script: +Nodes must be able to resolve `$REGISTRY_DOMAIN` name to the static IP address +of the local registry. One way to do this without an external DNS server is to use the +node's hosts file. For example, if the registry is on 10.0.0.2, then add this to the Node +configuration script: ```console echo "10.0.0.2 $REGISTRY_DOMAIN_NAME" >> /etc/hosts From 6d4f7b16820ba668ae38f8fb6d09a639f0c0a629 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 13 Apr 2021 14:56:12 -0500 Subject: [PATCH 13/16] Minor edits --- setup/air-gapped/infrastructure.md | 73 +++++++++++++++--------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index 98dc1369e..c55145dd8 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -3,10 +3,11 @@ title: Air-Gapped Network Setup description: Learn how to set up a network for air-gapped Coder deployment. --- -This article walks through setting up a the supporting infrastructure for -an air-gapped Coder deployment. +This article walks you through setting up the supporting infrastructure for an +air-gapped Coder deployment. -If the network already has the following, proceed with [the installation](../air-gapped): +If the network that will run Coder already has the following, skip this tutorial +and proceed with [the installation](../air-gapped) process: - A certificate authority - A domain name service @@ -14,16 +15,16 @@ If the network already has the following, proceed with [the installation](../air > The code snippets provided in this article are sourced from third-party > software packages. While we attempt to keep this article up-to-date, we -> strongly recommend that you verify the snippets as well before using. +> strongly recommend that you verify the snippets before using them. ## Creating the local registry and generating a self-signed certificate -To operate, Coder needs an image registry to store your Coder images. -Docker's `registry:2` image assumes that HTTPS will be used and supports -self-signed certificates. +Coder needs an image registry to store your images. It uses Docker's Registry +2.0 implementation, which supports self-signed certificates and assumes that the +protocol used will be HTTPS. The following steps will show you how to make sure +the registry works. -Before starting the registry container, create a self-signed certificate at the -with a command like: +Before starting the registry container, create a self-signed certificate: ```bash export REGISTRY_DOMAINNAME=registry.local @@ -53,10 +54,10 @@ docker run -d -p 443:5000 \ ## Configuring the Kubernetes Node -Before the Kubernetes node can accept run local images, it needs to consider the new -`registry.crt` file as trusted. The specific locations and methods to store and -trust the certificate vary depending on the Linux distribution and the container -runtime, but here is a partial list to start with: +Before the Kubernetes node can accept run local images, it needs to consider the +new `registry.crt` file as trusted. The specific locations and methods to store +and trust the certificate vary depending on the Linux distribution and the +container runtime, but here is a partial list to help you get started: ```plaintext /usr/local/share/ca-certificates/registry.crt @@ -65,8 +66,8 @@ runtime, but here is a partial list to start with: /etc/pki/tls/registry.crt ``` -If the cluster uses containerd, apply the following to patch in certificates -for images in the local registry domain: +If the cluster uses containerd, apply the following to patch in certificates for +images in the local registry domain: ```console update-ca-certificates @@ -77,19 +78,19 @@ EOT systemctl restart containerd ``` -Because the steps described in this section must be run on all nodes which -will be scheduling Coder images, it is best to: +Because the steps described in this section must be run on all nodes which will +be scheduling Coder images, either: -1. Include these steps in the image itself -1. Run an init script including these instructions whenever you add a new node - to your cluster +1. Include these steps in the image +1. Run an init script that includes these instructions whenever you add a new + node to your cluster ## Adding certificate secrets to the Helm chart -Coder validates images and pulls tags using direct REST API calls to the registry. -Other internal services (OICD, Git providers, etc) which use HTTPS APIs require -the Coder container to trust the certificate. The Coder helm chart can be used to -add a root CA certificate to the Coder service images. +Coder validates images and pulls tags using REST API calls to the registry. +Other internal services (OIDC, Git providers, etc) that use HTTPS APIs require +the Coder container to trust the certificate. You can fix this by adding a root +CA certificate to the Coder service images via the Coder helm chart. To pass a self-signed certificate to Coder's images, you'll need to: @@ -102,13 +103,13 @@ To create a secret, run: kubectl -n coder create secret generic local-registry-cert --from-file=/certs ``` -When using the above command, `kubectl` creates the secret from a directory with a -single file. The directory name doesn't matter, but the filename becomes the -secret **key**. +When using the above command, `kubectl` creates the secret from a directory +containing a single file. The directory name doesn't matter, but the filename +becomes the secret **key**. -> If you changed the `-out` argument on the OpenSSL command used to generate the -> certificates, or if you moved the certificates, make sure that you adjust the -> path included with `--from-file=`. +> If you changed the `-keyout` argument on the OpenSSL command used to generate +> the certificates, or if you moved the certificates, make sure that you adjust +> the path included with `--from-file=`. To verify the new secret: @@ -116,8 +117,8 @@ To verify the new secret: kubectl -n coder get secret local-registry-cert -o yaml ``` -Reference the newly secret from the Helm chart by adding the following -snippet into a YAML file named `registry-cert-values.yml`: +Refer to the new secret from the Helm chart by adding the following snippet into +a YAML file named `registry-cert-values.yml`: ```yaml certs: @@ -135,10 +136,10 @@ kubectl -n coder get secret local-registry-cert -o yaml -f registry-cert-values. ### Resolving the registry using the cluster's DNS or hostAliases -Nodes must be able to resolve `$REGISTRY_DOMAIN` name to the static IP address -of the local registry. One way to do this without an external DNS server is to use the -node's hosts file. For example, if the registry is on 10.0.0.2, then add this to the Node -configuration script: +Nodes must be able to resolve the `$REGISTRY_DOMAIN` name of the local +registry's static IP address. One way to do this without an external DNS server +is to use the node's hosts file. For example, if the registry is on 10.0.0.2, +then add this to the Node configuration script: ```console echo "10.0.0.2 $REGISTRY_DOMAIN_NAME" >> /etc/hosts From be29c60f2abb5995dffadd4681586ae15549ee93 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 13 Apr 2021 15:12:03 -0500 Subject: [PATCH 14/16] Fix broken link --- setup/air-gapped/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index 29732ea34..e03054cf1 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -168,9 +168,9 @@ platform images are hosted in Coder's Docker Hub repo. -f registry-cert-values.yml ``` -1. Next, follow the [Installation](installation.md) guide beginning with **step - 6** to get the access URL and the temporary admin password, which allows you - to proceed with setting up and configuring Coder. +1. Next, follow the [Installation](../installation.md) guide beginning with + **step 6** to get the access URL and the temporary admin password, which + allows you to proceed with setting up and configuring Coder. ## Extensions marketplace From bae18d53c75788549ddfb78e92a8ed3a27a9807c Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 13 Apr 2021 15:35:21 -0500 Subject: [PATCH 15/16] Fix more broken links --- setup/air-gapped/index.md | 4 ++-- setup/air-gapped/infrastructure.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/setup/air-gapped/index.md b/setup/air-gapped/index.md index e03054cf1..ad92c074f 100644 --- a/setup/air-gapped/index.md +++ b/setup/air-gapped/index.md @@ -113,7 +113,7 @@ platform images are hosted in Coder's Docker Hub repo. When building images for your environments that rely on a custom certificate authority, be sure to follow the - [docs for adding certificates](/docs/images/ssl-certificates#adding-certificates-for-coder) + [docs for adding certificates](../../images/ssl-certificates#adding-certificates-for-coder) to images. 1. Tag and push all of the images that you've downloaded in the previous step to @@ -178,7 +178,7 @@ Coder users in an air-gapped environment cannot access the public VS Code marketplace. However, you can point Coder to an air-gapped instance of [OpenVSX](https://github.com/eclipse/openvsx) to serve assets to users. For instructions on implementing this, see -[Extensions](../admin/environment-management/extensions.md). +[Extensions](../../admin/environment-management/extensions.md). You can also review the [OpenVSX deployment wiki] for more information. diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index c55145dd8..cc38b76ef 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -7,7 +7,7 @@ This article walks you through setting up the supporting infrastructure for an air-gapped Coder deployment. If the network that will run Coder already has the following, skip this tutorial -and proceed with [the installation](../air-gapped) process: +and proceed with [the installation](index.md) process: - A certificate authority - A domain name service From 21874dbcb08e7d2eba32c9d9220ab47e61321cd9 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 13 Apr 2021 15:47:01 -0500 Subject: [PATCH 16/16] Reorder nav, fix title --- manifest.json | 4 ++-- setup/air-gapped/infrastructure.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/manifest.json b/manifest.json index cf5d16ca9..6d509e2fa 100644 --- a/manifest.json +++ b/manifest.json @@ -135,11 +135,11 @@ { "path": "./setup/installation.md" }, { "path": "./setup/configuration.md" }, { "path": "./setup/licensing.md" }, + { "path": "./setup/updating.md" }, { "path": "./setup/air-gapped/index.md", "children": [{ "path": "./setup/air-gapped/infrastructure.md" }] - }, - { "path": "./setup/updating.md" } + } ] }, { diff --git a/setup/air-gapped/infrastructure.md b/setup/air-gapped/infrastructure.md index cc38b76ef..340d48370 100644 --- a/setup/air-gapped/infrastructure.md +++ b/setup/air-gapped/infrastructure.md @@ -1,5 +1,5 @@ --- -title: Air-Gapped Network Setup +title: Network Setup description: Learn how to set up a network for air-gapped Coder deployment. ---