diff --git a/docs/images/icons/rancher.svg b/docs/images/icons/rancher.svg new file mode 100644 index 0000000000000..c737e6b1dde96 --- /dev/null +++ b/docs/images/icons/rancher.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/images/install/coder-rancher.png b/docs/images/install/coder-rancher.png new file mode 100644 index 0000000000000..95471617b59ae Binary files /dev/null and b/docs/images/install/coder-rancher.png differ diff --git a/docs/install/rancher.md b/docs/install/rancher.md new file mode 100644 index 0000000000000..5a8832e81c526 --- /dev/null +++ b/docs/install/rancher.md @@ -0,0 +1,161 @@ +# Deploy Coder on Rancher + +You can deploy Coder on Rancher as a +[Workload](https://ranchermanager.docs.rancher.com/getting-started/quick-start-guides/deploy-workloads/workload-ingress). + +## Requirements + +- [SUSE Rancher Manager](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster) running Kubernetes (K8s) 1.19+ with [SUSE Rancher Prime distribution](https://documentation.suse.com/cloudnative/rancher-manager/latest/en/integrations/kubernetes-distributions.html) (Rancher Manager 2.10+) +- Helm 3.5+ installed +- Workload Kubernetes cluster for Coder + +## Overview + +Installing Coder on Rancher involves four key steps: + +1. Create a namespace for Coder +1. Set up PostgreSQL +1. Create a database connection secret +1. Install the Coder application via Rancher UI + +## Create a namespace + +Create a namespace for the Coder control plane. In this tutorial, we call it `coder`: + +```shell +kubectl create namespace coder +``` + +## Set up PostgreSQL + +Coder requires a PostgreSQL database to store deployment data. +We recommend that you use a managed PostgreSQL service, but you can use an in-cluster PostgreSQL service for non-production deployments: + +
+ +### Managed PostgreSQL (Recommended) + +For production deployments, we recommend using a managed PostgreSQL service: + +- [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/) +- [AWS RDS for PostgreSQL](https://aws.amazon.com/rds/postgresql/) +- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/) +- [DigitalOcean Managed PostgreSQL](https://www.digitalocean.com/products/managed-databases-postgresql) + +Ensure that your PostgreSQL service: + +- Is running and accessible from your cluster +- Is in the same network/project as your cluster +- Has proper credentials and a database created for Coder + +### In-Cluster PostgreSQL (Development/PoC) + +For proof-of-concept deployments, you can use Bitnami Helm chart to install PostgreSQL in your Kubernetes cluster: + +```console +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 +``` + +After installation, the cluster-internal database URL will be: + +```text +postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable +``` + +For more advanced PostgreSQL management, consider using the +[Postgres operator](https://github.com/zalando/postgres-operator). + +
+ +## Create the database connection secret + +Create a Kubernetes secret with your PostgreSQL connection URL: + +```shell +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" +``` + +> [!Important] +> If you're using a managed PostgreSQL service, replace the connection URL with your specific database credentials. + +## Install Coder through the Rancher UI + +![Coder installed on Rancher](../images/install/coder-rancher.png) + +1. In the Rancher Manager console, select your target Kubernetes cluster for Coder. + +1. Navigate to **Apps** > **Charts** + +1. From the dropdown menu, select **Partners** and search for `Coder` + +1. Select **Coder**, then **Install** + +1. Select the `coder` namespace you created earlier and check **Customize Helm options before install**. + + Select **Next** + +1. On the configuration screen, select **Edit YAML** and enter your Coder configuration settings: + +
+ Example values.yaml configuration + + ```yaml + coder: + # Environment variables for Coder + env: + - name: CODER_PG_CONNECTION_URL + valueFrom: + secretKeyRef: + name: coder-db-url + key: url + + # For production, uncomment and set your access URL + # - name: CODER_ACCESS_URL + # value: "https://coder.example.com" + + # For TLS configuration (uncomment if needed) + #tls: + # secretNames: + # - my-tls-secret-name + ``` + + For available configuration options, refer to the [Helm chart documentation](https://github.com/coder/coder/blob/main/helm#readme) + or [values.yaml file](https://github.com/coder/coder/blob/main/helm/coder/values.yaml). + +
+ +1. Select a Coder version: + + - **Mainline**: `2.20.x` + - **Stable**: `2.19.x` + + Learn more about release channels in the [Releases documentation](./releases.md). + +1. Select **Next** when your configuration is complete. + +1. On the **Supply additional deployment options** screen: + + 1. Accept the default settings + 1. Select **Install** + +1. A Helm install output shell will be displayed and indicates the installation status. + +## Manage your Rancher Coder deployment + +To update or manage your Coder deployment later: + +1. Navigate to **Apps** > **Installed Apps** in the Rancher UI. +1. Find and select Coder. +1. Use the options in the **⋮** menu for upgrade, rollback, or other operations. + +## Next steps + +- [Create your first template](../tutorials/template-from-scratch.md) +- [Control plane configuration](../admin/setup/index.md) diff --git a/docs/manifest.json b/docs/manifest.json index 7352b8afd61fa..f37f9a9db67f7 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -48,6 +48,12 @@ "path": "./install/kubernetes.md", "icon_path": "./images/icons/kubernetes.svg" }, + { + "title": "Rancher", + "description": "Deploy Coder on Rancher", + "path": "./install/rancher.md", + "icon_path": "./images/icons/rancher.svg" + }, { "title": "OpenShift", "description": "Install Coder on OpenShift",