mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
co-authored by
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
parent
288df75686
commit
419eba5fb6
+123
-128
@@ -1,164 +1,159 @@
|
||||
# Install Coder on Kubernetes
|
||||
|
||||
You can install Coder on Kubernetes using Helm. We run on most Kubernetes
|
||||
distributions, including [OpenShift](./other/openshift.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
Before proceeding, please ensure that you have a Kubernetes cluster running K8s
|
||||
1.19+ and have Helm 3.5+ installed.
|
||||
- Kubernetes cluster running K8s 1.19+
|
||||
- [Helm](https://helm.sh/docs/intro/install/) 3.5+ installed on your local
|
||||
machine
|
||||
|
||||
You'll also want to install the
|
||||
[latest version of Coder](https://github.com/coder/coder/releases/latest)
|
||||
locally in order to log in and manage templates.
|
||||
## 1. Create a namespace
|
||||
|
||||
> Coder supports two release channels: mainline for the true latest version of
|
||||
> Coder, and stable for large enterprise deployments. Before installing your
|
||||
> control plane via Helm, please read the [Releases](./releases.md) document to
|
||||
> identify the best-suited release for your team, then specify the version using
|
||||
> Helm's `--version` flag.
|
||||
Create a namespace for the Coder control plane. In this tutorial, we'll call it
|
||||
`coder`.
|
||||
|
||||
> The version flags for both stable and mainline are automatically filled in
|
||||
> this page.
|
||||
```sh
|
||||
kubectl create namespace coder
|
||||
```
|
||||
|
||||
> If you need help setting up k8s, we have a
|
||||
> [repo with Terraform configuration](https://github.com/ElliotG/coder-oss-tf)
|
||||
> to provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS,
|
||||
> IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule.
|
||||
## 2. Create a PostgreSQL instance
|
||||
|
||||
## Install Coder with Helm
|
||||
Coder does not manage a database server for you. This is required for storing
|
||||
data about your Coder deployment and resources.
|
||||
|
||||
1. Create a namespace for Coder, such as `coder`:
|
||||
### Managed PostgreSQL (recommended)
|
||||
|
||||
```console
|
||||
kubectl create namespace coder
|
||||
```
|
||||
If you're in a public cloud such as
|
||||
[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
|
||||
[AWS](https://aws.amazon.com/rds/postgresql/),
|
||||
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
|
||||
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
|
||||
you can use the managed PostgreSQL offerings they provide. Make sure that the
|
||||
PostgreSQL service is running and accessible from your cluster. It should be in
|
||||
the same network, same project, etc.
|
||||
|
||||
1. Create a PostgreSQL deployment. Coder does not manage a database server for
|
||||
you.
|
||||
### In-Cluster PostgreSQL (for proof of concepts)
|
||||
|
||||
If you're in a public cloud such as
|
||||
[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
|
||||
[AWS](https://aws.amazon.com/rds/postgresql/),
|
||||
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
|
||||
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
|
||||
you can use the managed PostgreSQL offerings they provide. Make sure that the
|
||||
PostgreSQL service is running and accessible from your cluster. It should be
|
||||
in the same network, same project, etc.
|
||||
You can install Postgres manually on your cluster using the
|
||||
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
|
||||
There are some [helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes)
|
||||
on the internet that explain sensible configurations for this chart. Example:
|
||||
|
||||
You can install Postgres manually on your cluster using the
|
||||
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
|
||||
There are some
|
||||
[helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
|
||||
internet that explain sensible configurations for this chart. Example:
|
||||
```console
|
||||
# Install PostgreSQL
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm install coder-db bitnami/postgresql \
|
||||
--namespace coder \
|
||||
--set auth.username=coder \
|
||||
--set auth.password=coder \
|
||||
--set auth.database=coder \
|
||||
--set persistence.size=10Gi
|
||||
```
|
||||
|
||||
```console
|
||||
# Install PostgreSQL
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm install coder-db bitnami/postgresql \
|
||||
--namespace coder \
|
||||
--set auth.username=coder \
|
||||
--set auth.password=coder \
|
||||
--set auth.database=coder \
|
||||
--set persistence.size=10Gi
|
||||
```
|
||||
The cluster-internal DB URL for the above database is:
|
||||
|
||||
The cluster-internal DB URL for the above database is:
|
||||
```shell
|
||||
postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
|
||||
```
|
||||
|
||||
```shell
|
||||
postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
|
||||
```
|
||||
You can optionally use the
|
||||
[Postgres operator](https://github.com/zalando/postgres-operator) to manage
|
||||
PostgreSQL deployments on your Kubernetes cluster.
|
||||
|
||||
> Ensure you set up periodic backups so you don't lose data.
|
||||
## 3. Create the PostgreSQL secret
|
||||
|
||||
You can use [Postgres operator](https://github.com/zalando/postgres-operator)
|
||||
to manage PostgreSQL deployments on your Kubernetes cluster.
|
||||
Create a secret with the PostgreSQL database URL string. In the case of the
|
||||
self-managed PostgreSQL, the address will be:
|
||||
|
||||
1. Create a secret with the database URL:
|
||||
```sh
|
||||
kubectl create secret generic coder-db-url -n coder \
|
||||
--from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
|
||||
```
|
||||
|
||||
```shell
|
||||
# Uses Bitnami PostgreSQL example. If you have another database,
|
||||
# change to the proper URL.
|
||||
kubectl create secret generic coder-db-url -n coder \
|
||||
--from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
|
||||
```
|
||||
## 4. Install Coder with Helm
|
||||
|
||||
1. Add the Coder Helm repo:
|
||||
```shell
|
||||
helm repo add coder-v2 https://helm.coder.com/v2
|
||||
```
|
||||
|
||||
```shell
|
||||
helm repo add coder-v2 https://helm.coder.com/v2
|
||||
```
|
||||
Create a `values.yaml` with the configuration settings you'd like for your
|
||||
deployment. For example:
|
||||
|
||||
1. Create a `values.yaml` with the configuration settings you'd like for your
|
||||
deployment. For example:
|
||||
```yaml
|
||||
coder:
|
||||
# You can specify any environment variables you'd like to pass to Coder
|
||||
# here. Coder consumes environment variables listed in
|
||||
# `coder server --help`, and these environment variables are also passed
|
||||
# to the workspace provisioner (so you can consume them in your Terraform
|
||||
# templates for auth keys etc.).
|
||||
#
|
||||
# Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
|
||||
# `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
|
||||
# they are already set by the Helm chart and will cause conflicts.
|
||||
env:
|
||||
- name: CODER_PG_CONNECTION_URL
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
# You'll need to create a secret called coder-db-url with your
|
||||
# Postgres connection URL like:
|
||||
# postgres://coder:password@postgres:5432/coder?sslmode=disable
|
||||
name: coder-db-url
|
||||
key: url
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
# You can specify any environment variables you'd like to pass to Coder
|
||||
# here. Coder consumes environment variables listed in
|
||||
# `coder server --help`, and these environment variables are also passed
|
||||
# to the workspace provisioner (so you can consume them in your Terraform
|
||||
# templates for auth keys etc.).
|
||||
#
|
||||
# Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
|
||||
# `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
|
||||
# they are already set by the Helm chart and will cause conflicts.
|
||||
env:
|
||||
- name: CODER_PG_CONNECTION_URL
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
# You'll need to create a secret called coder-db-url with your
|
||||
# Postgres connection URL like:
|
||||
# postgres://coder:password@postgres:5432/coder?sslmode=disable
|
||||
name: coder-db-url
|
||||
key: url
|
||||
# (Optional) For production deployments the access URL should be set.
|
||||
# If you're just trying Coder, access the dashboard via the service IP.
|
||||
- name: CODER_ACCESS_URL
|
||||
value: "https://coder.example.com"
|
||||
|
||||
# (Optional) For production deployments the access URL should be set.
|
||||
# If you're just trying Coder, access the dashboard via the service IP.
|
||||
- name: CODER_ACCESS_URL
|
||||
value: "https://coder.example.com"
|
||||
#tls:
|
||||
# secretNames:
|
||||
# - my-tls-secret-name
|
||||
```
|
||||
|
||||
#tls:
|
||||
# secretNames:
|
||||
# - my-tls-secret-name
|
||||
```
|
||||
> You can view our
|
||||
> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
|
||||
> details on the values that are available, or you can view the
|
||||
> [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
|
||||
> file directly.
|
||||
|
||||
> You can view our
|
||||
> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
|
||||
> details on the values that are available, or you can view the
|
||||
> [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
|
||||
> file directly.
|
||||
We support two release channels: mainline and stable - read the
|
||||
[Releases](./releases.md) page to learn more about which best suits your team.
|
||||
|
||||
1. Run the following command to install the chart in your cluster.
|
||||
|
||||
For the **mainline** Coder release:
|
||||
For the **mainline** Coder release:
|
||||
|
||||
<!-- autoversion(mainline): "--version [version]" -->
|
||||
|
||||
```shell
|
||||
helm install coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--values values.yaml \
|
||||
--version 2.16.0
|
||||
```
|
||||
```shell
|
||||
helm install coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--values values.yaml \
|
||||
--version 2.15.0
|
||||
```
|
||||
|
||||
For the **stable** Coder release:
|
||||
For the **stable** Coder release:
|
||||
|
||||
<!-- autoversion(stable): "--version [version]" -->
|
||||
<!-- autoversion(stable): "--version [version]" -->
|
||||
|
||||
```shell
|
||||
helm install coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--values values.yaml \
|
||||
--version 2.15.1
|
||||
```
|
||||
```shell
|
||||
helm install coder coder-v2/coder \
|
||||
--namespace coder \
|
||||
--values values.yaml \
|
||||
--version 2.15.1
|
||||
```
|
||||
|
||||
You can watch Coder start up by running `kubectl get pods -n coder`. Once
|
||||
Coder has started, the `coder-*` pods should enter the `Running` state.
|
||||
You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder
|
||||
has started, the `coder-*` pods should enter the `Running` state.
|
||||
|
||||
1. Log in to Coder
|
||||
## 5. Log in to Coder 🎉
|
||||
|
||||
Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer.
|
||||
Visit this in the browser to set up your first account.
|
||||
Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer. Visit
|
||||
this in the browser to set up your first account.
|
||||
|
||||
If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
|
||||
the Helm chart and upgrade Coder (see below). This allows workspaces to
|
||||
connect to the proper Coder URL.
|
||||
If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
|
||||
the Helm chart and upgrade Coder (see below). This allows workspaces to connect
|
||||
to the proper Coder URL.
|
||||
|
||||
## Upgrading Coder via Helm
|
||||
|
||||
@@ -292,10 +287,10 @@ Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm
|
||||
chart. If you do not have a domain set up, this should be the IP address of
|
||||
Coder's LoadBalancer (`kubectl get svc -n coder`).
|
||||
|
||||
See [troubleshooting templates](../templates/index.md#troubleshooting-templates)
|
||||
for more steps.
|
||||
See [troubleshooting templates](../admin/templates/troubleshooting.md) for more
|
||||
steps.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Configuring Coder](../admin/configure.md)
|
||||
- [Templates](../templates/index.md)
|
||||
- [Create your first template](../tutorials/template-from-scratch.md)
|
||||
- [Control plane configuration](../admin/setup/index.md)
|
||||
|
||||
Reference in New Issue
Block a user