integrations

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit a3f2e84700748fec18681c0fc4fd7b2fb0f98c59
diff --git a/docs/admin/integrations/README.md b/docs/admin/integrations/README.md
@@ -0,0 +1,3 @@
+# Integrations
+
+TODO: Landing for integrations
diff --git a/docs/admin/integrations/kubernetes-logs.md b/docs/admin/integrations/kubernetes-logs.md
@@ -0,0 +1,78 @@
+# Kubernetes event logs
+
+To stream Kubernetes events into your workspace startup logs, you can use
+Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube)
+tool. `coder-logstream-kube` provides useful information about the workspace pod
+or deployment, such as:
+
+- Causes of pod provisioning failures, or why a pod is stuck in a pending state.
+- Visibility into when pods are OOMKilled, or when they are evicted.
+
+## Prerequisites
+
+`coder-logstream-kube` works best with the
+[`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment)
+Terraform resource, which requires the `coder` service account to have
+permission to create deployments. For example, if you use
+[Helm](../../install/kubernetes.md#install-coder-with-helm) to install Coder,
+you should set `coder.serviceAccount.enableDeployments=true` in your
+`values.yaml`
+
+```diff
+coder:
+serviceAccount:
+    workspacePerms: true
+-   enableDeployments: false
++   enableDeployments: true
+    annotations: {}
+    name: coder
+```
+
+> Note: This is only required for Coder versions < 0.28.0, as this will be the
+> default value for Coder versions >= 0.28.0
+
+## Installation
+
+Install the `coder-logstream-kube` helm chart on the cluster where the
+deployment is running.
+
+```shell
+helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
+helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
+    --namespace coder \
+    --set url=<your-coder-url-including-http-or-https>
+```
+
+## Example logs
+
+Here is an example of the logs you can expect to see in the workspace startup
+logs:
+
+### Normal pod deployment
+
+![normal pod deployment](../../images/admin/integrations/coder-logstream-kube-logs-normal.png)
+
+### Wrong image
+
+![Wrong image name](../../images/admin/integrations/coder-logstream-kube-logs-wrong-image.png)
+
+### Kubernetes quota exceeded
+
+![Kubernetes quota exceeded](../../images/admin/integrations/coder-logstream-kube-logs-quota-exceeded.png)
+
+### Pod crash loop
+
+![Pod crash loop](../../images/admin/integrations/coder-logstream-kube-logs-pod-crashed.png)
+
+## How it works
+
+Kubernetes provides an
+[informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod
+and event data from the API server.
+
+coder-logstream-kube listens for pod creation events with containers that have
+the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as
+logs to the Coder API using the agent token for authentication. For more
+details, see the
+[coder-logstream-kube](https://github.com/coder/coder-logstream-kube)
+repository.
diff --git a/docs/admin/integrations/multiple-kube-clusters.md b/docs/admin/integrations/multiple-kube-clusters.md
@@ -0,0 +1,236 @@
+# Additional clusters
+
+With Coder, you can deploy workspaces in additional Kubernetes clusters using
+different
+[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
+in the Terraform provider.
+
+![Region picker in "Create Workspace" screen](../../images/admin/integrations/kube-region-picker.png)
+
+## Option 1) Kubernetes contexts and kubeconfig
+
+First, create a kubeconfig file with
+[multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
+
+```shell
+kubectl config get-contexts
+
+CURRENT   NAME                        CLUSTER
+          workspaces-europe-west2-c   workspaces-europe-west2-c
+*         workspaces-us-central1-a    workspaces-us-central1-a
+```
+
+### Kubernetes control plane
+
+If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret.
+
+This assumes Coder is deployed on the `coder` namespace and your kubeconfig file
+is in ~/.kube/config.
+
+```shell
+kubectl create secret generic kubeconfig-secret -n coder --from-file=~/.kube/config
+```
+
+Modify your helm values to mount the secret:
+
+```yaml
+coder:
+  # ...
+  volumes:
+    - name: "kubeconfig-mount"
+      secret:
+        secretName: "kubeconfig-secret"
+  volumeMounts:
+    - name: "kubeconfig-mount"
+      mountPath: "/mnt/secrets/kube"
+      readOnly: true
+```
+
+[Upgrade Coder](../../install/kubernetes.md#upgrading-coder-via-helm) with these
+new values.
+
+### VM control plane
+
+If you deployed Coder on a VM, copy the kubeconfig file to
+`/home/coder/.kube/config`.
+
+### Create a Coder template
+
+You can start from our
+[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+From there, add [template parameters](../../templates/concepts/parameters.md) to allow
+developers to pick their desired cluster.
+
+```hcl
+# main.tf
+
+data "coder_parameter" "kube_context" {
+  name         = "kube_context"
+  display_name = "Cluster"
+  default      = "workspaces-us-central1-a"
+  mutable      = false
+  option {
+    name  = "US Central"
+    icon  = "/emojis/1f33d.png"
+    value = "workspaces-us-central1-a"
+  }
+  option {
+    name  = "Europe West"
+    icon  = "/emojis/1f482.png"
+    value = "workspaces-europe-west2-c"
+  }
+}
+
+provider "kubernetes" {
+  config_path    = "~/.kube/config" # or /mnt/secrets/kube/config for Kubernetes
+  config_context = data.coder_parameter.kube_context.value
+}
+```
+
+## Option 2) Kubernetes ServiceAccounts
+
+Alternatively, you can authenticate with remote clusters with ServiceAccount
+tokens. Coder can store these secrets on your behalf with
+[managed Terraform variables](../templates/concepts/variables.md).
+
+Alternatively, these could also be fetched from Kubernetes secrets or even
+[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret).
+
+This guide assumes you have a `coder-workspaces` namespace on your remote
+cluster. Change the namespace accordingly.
+
+### Create a ServiceAccount
+
+Run this command against your remote cluster to create a ServiceAccount, Role,
+RoleBinding, and token:
+
+```shell
+kubectl apply -n coder-workspaces -f - <<EOF
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: coder-v2
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: coder-v2
+  annotations:
+    kubernetes.io/service-account.name: coder-v2
+type: kubernetes.io/service-account-token
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: coder-v2
+rules:
+  - apiGroups: ["", "apps", "networking.k8s.io"]
+    resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
+    verbs: ["create", "get", "list", "watch", "update", "patch", "delete", "deletecollection"]
+  - apiGroups: ["metrics.k8s.io", "storage.k8s.io"]
+    resources: ["pods", "storageclasses"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: coder-v2
+subjects:
+  - kind: ServiceAccount
+    name: coder-v2
+roleRef:
+  kind: Role
+  name: coder-v2
+  apiGroup: rbac.authorization.k8s.io
+EOF
+```
+
+The output should be similar to:
+
+```text
+serviceaccount/coder-v2 created
+secret/coder-v2 created
+role.rbac.authorization.k8s.io/coder-v2 created
+rolebinding.rbac.authorization.k8s.io/coder-v2 created
+```
+
+### 2. Modify the Kubernetes template
+
+You can start from our
+[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
+
+```hcl
+variable "host" {
+  description = "Cluster host address"
+  sensitive   = true
+}
+
+variable "cluster_ca_certificate" {
+  description = "Cluster CA certificate (base64 encoded)"
+  sensitive   = true
+}
+
+variable "token" {
+  description = "Cluster CA token (base64 encoded)"
+  sensitive   = true
+}
+
+variable "namespace" {
+  description = "Namespace"
+}
+
+provider "kubernetes" {
+  host                   = var.host
+  cluster_ca_certificate = base64decode(var.cluster_ca_certificate)
+  token                  = base64decode(var.token)
+}
+```
+
+### Create Coder template with managed variables
+
+Fetch the values from the secret and pass them to Coder. This should work on
+macOS and Linux.
+
+To get the cluster address:
+
+```shell
+kubectl cluster-info
+Kubernetes control plane is running at https://example.domain:6443
+
+export CLUSTER_ADDRESS=https://example.domain:6443
+```
+
+To fetch the CA certificate and token:
+
+```shell
+export CLUSTER_CA_CERTIFICATE=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.ca\.crt}")
+
+export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.token}")
+```
+
+Create the template with these values:
+
+```shell
+coder templates push \
+    --variable host=$CLUSTER_ADDRESS \
+    --variable cluster_ca_certificate=$CLUSTER_CA_CERTIFICATE \
+    --variable token=$CLUSTER_SERVICEACCOUNT_TOKEN \
+    --variable namespace=coder-workspaces
+```
+
+If you're on a Windows machine (or if one of the commands fail), try grabbing
+the values manually:
+
+```shell
+# Get cluster API address
+kubectl cluster-info
+
+# Get cluster CA and token (base64 encoded)
+kubectl get secrets coder-service-account-token -n coder-workspaces -o jsonpath="{.data}"
+
+coder templates push \
+    --variable host=API_ADDRESS \
+    --variable cluster_ca_certificate=CLUSTER_CA_CERTIFICATE \
+    --variable token=CLUSTER_SERVICEACCOUNT_TOKEN \
+    --variable namespace=coder-workspaces
+```
diff --git a/docs/admin/integrations/opentofu.md b/docs/admin/integrations/opentofu.md
@@ -0,0 +1,17 @@
+# Provisioning with OpenTofu
+
+<!-- Keeping this in as a placeholder for supporting OpenTofu. We should fix support for custom terraform binaries ASAP. -->
+
+> ⚠️ This guide is a work in progress. We do not officially support using custom Terraform binaries in your Coder deployment. To track progress on the work, see this related [Github Issue](https://github.com/coder/coder/issues/12009). 
+
+Coder deployments support any custom Terraform binary, including [OpenTofu](https://opentofu.org/docs/) - an open source alternative to Terraform. 
+
+> You can read more about OpenTofu and Hashicorp's licensing in our [blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. 
+
+
+
+## Using a custom Terraform binary
+
+You can change your deployment custom Terraform binary as long as it is in `PATH` and is within the [supported versions](https://github.com/coder/coder/blob/f57ce97b5aadd825ddb9a9a129bb823a3725252b/provisioner/terraform/install.go#L22-L25). The hardcoded version check ensures compatibility with our [example templates](https://github.com/coder/coder/tree/main/examples/templates).
+
+
diff --git a/docs/admin/integrations/other.md b/docs/admin/integrations/other.md
@@ -0,0 +1,15 @@
+# Other platforms
+
+Coder is highly extensible and is not limited to the platforms outlined in these
+docs. The control plane can be provisioned on any VM or container compute, and
+workspaces can include any Terraform resource. See our
+[architecture diagram](../infrastructure/architecture.md) for more details.
+
+The following resources may help as you're deploying Coder.
+
+- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
+- [Deploy Coder offline](../../install/offline.md)
+- [Supported resources (Terraform registry)](https://registry.terraform.io)
+- [Writing custom templates](../templates/README.md)
+
+<!-- TODO: writing custom templates link-->