Skip to content

Commit a3f2e84

Browse files
stirbymatifali
stirby
authored and
matifali
committed
integrations
1 parent 79ee974 commit a3f2e84

13 files changed

+553
-3
lines changed

‎docs/admin/integrations/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integrations
2+
3+
TODO: Landing for integrations

‎docs/admin/integrations/kubernetes-logs.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Kubernetes event logs
2+
3+
To stream Kubernetes events into your workspace startup logs, you can use
4+
Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube)
5+
tool. `coder-logstream-kube` provides useful information about the workspace pod
6+
or deployment, such as:
7+
8+
- Causes of pod provisioning failures, or why a pod is stuck in a pending state.
9+
- Visibility into when pods are OOMKilled, or when they are evicted.
10+
11+
## Prerequisites
12+
13+
`coder-logstream-kube` works best with the
14+
[`kubernetes_deployment`](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/deployment)
15+
Terraform resource, which requires the `coder` service account to have
16+
permission to create deployments. For example, if you use
17+
[Helm](../../install/kubernetes.md#install-coder-with-helm) to install Coder,
18+
you should set `coder.serviceAccount.enableDeployments=true` in your
19+
`values.yaml`
20+
21+
```diff
22+
coder:
23+
serviceAccount:
24+
workspacePerms: true
25+
- enableDeployments: false
26+
+ enableDeployments: true
27+
annotations: {}
28+
name: coder
29+
```
30+
31+
> Note: This is only required for Coder versions < 0.28.0, as this will be the
32+
> default value for Coder versions >= 0.28.0
33+
34+
## Installation
35+
36+
Install the `coder-logstream-kube` helm chart on the cluster where the
37+
deployment is running.
38+
39+
```shell
40+
helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
41+
helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
42+
--namespace coder \
43+
--set url=<your-coder-url-including-http-or-https>
44+
```
45+
46+
## Example logs
47+
48+
Here is an example of the logs you can expect to see in the workspace startup
49+
logs:
50+
51+
### Normal pod deployment
52+
53+
![normal pod deployment](../../images/admin/integrations/coder-logstream-kube-logs-normal.png)
54+
55+
### Wrong image
56+
57+
![Wrong image name](../../images/admin/integrations/coder-logstream-kube-logs-wrong-image.png)
58+
59+
### Kubernetes quota exceeded
60+
61+
![Kubernetes quota exceeded](../../images/admin/integrations/coder-logstream-kube-logs-quota-exceeded.png)
62+
63+
### Pod crash loop
64+
65+
![Pod crash loop](../../images/admin/integrations/coder-logstream-kube-logs-pod-crashed.png)
66+
67+
## How it works
68+
69+
Kubernetes provides an
70+
[informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod
71+
and event data from the API server.
72+
73+
coder-logstream-kube listens for pod creation events with containers that have
74+
the CODER_AGENT_TOKEN environment variable set. All pod events are streamed as
75+
logs to the Coder API using the agent token for authentication. For more
76+
details, see the
77+
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube)
78+
repository.

‎docs/admin/integrations/multiple-kube-clusters.md

+236
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Additional clusters
2+
3+
With Coder, you can deploy workspaces in additional Kubernetes clusters using
4+
different
5+
[authentication methods](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication)
6+
in the Terraform provider.
7+
8+
![Region picker in "Create Workspace" screen](../../images/admin/integrations/kube-region-picker.png)
9+
10+
## Option 1) Kubernetes contexts and kubeconfig
11+
12+
First, create a kubeconfig file with
13+
[multiple contexts](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
14+
15+
```shell
16+
kubectl config get-contexts
17+
18+
CURRENT NAME CLUSTER
19+
workspaces-europe-west2-c workspaces-europe-west2-c
20+
* workspaces-us-central1-a workspaces-us-central1-a
21+
```
22+
23+
### Kubernetes control plane
24+
25+
If you deployed Coder on Kubernetes, you can attach a kubeconfig as a secret.
26+
27+
This assumes Coder is deployed on the `coder` namespace and your kubeconfig file
28+
is in ~/.kube/config.
29+
30+
```shell
31+
kubectl create secret generic kubeconfig-secret -n coder --from-file=~/.kube/config
32+
```
33+
34+
Modify your helm values to mount the secret:
35+
36+
```yaml
37+
coder:
38+
# ...
39+
volumes:
40+
- name: "kubeconfig-mount"
41+
secret:
42+
secretName: "kubeconfig-secret"
43+
volumeMounts:
44+
- name: "kubeconfig-mount"
45+
mountPath: "/mnt/secrets/kube"
46+
readOnly: true
47+
```
48+
49+
[Upgrade Coder](../../install/kubernetes.md#upgrading-coder-via-helm) with these
50+
new values.
51+
52+
### VM control plane
53+
54+
If you deployed Coder on a VM, copy the kubeconfig file to
55+
`/home/coder/.kube/config`.
56+
57+
### Create a Coder template
58+
59+
You can start from our
60+
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
61+
From there, add [template parameters](../../templates/concepts/parameters.md) to allow
62+
developers to pick their desired cluster.
63+
64+
```hcl
65+
# main.tf
66+
67+
data "coder_parameter" "kube_context" {
68+
name = "kube_context"
69+
display_name = "Cluster"
70+
default = "workspaces-us-central1-a"
71+
mutable = false
72+
option {
73+
name = "US Central"
74+
icon = "/emojis/1f33d.png"
75+
value = "workspaces-us-central1-a"
76+
}
77+
option {
78+
name = "Europe West"
79+
icon = "/emojis/1f482.png"
80+
value = "workspaces-europe-west2-c"
81+
}
82+
}
83+
84+
provider "kubernetes" {
85+
config_path = "~/.kube/config" # or /mnt/secrets/kube/config for Kubernetes
86+
config_context = data.coder_parameter.kube_context.value
87+
}
88+
```
89+
90+
## Option 2) Kubernetes ServiceAccounts
91+
92+
Alternatively, you can authenticate with remote clusters with ServiceAccount
93+
tokens. Coder can store these secrets on your behalf with
94+
[managed Terraform variables](../templates/concepts/variables.md).
95+
96+
Alternatively, these could also be fetched from Kubernetes secrets or even
97+
[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret).
98+
99+
This guide assumes you have a `coder-workspaces` namespace on your remote
100+
cluster. Change the namespace accordingly.
101+
102+
### Create a ServiceAccount
103+
104+
Run this command against your remote cluster to create a ServiceAccount, Role,
105+
RoleBinding, and token:
106+
107+
```shell
108+
kubectl apply -n coder-workspaces -f - <<EOF
109+
apiVersion: v1
110+
kind: ServiceAccount
111+
metadata:
112+
name: coder-v2
113+
---
114+
apiVersion: v1
115+
kind: Secret
116+
metadata:
117+
name: coder-v2
118+
annotations:
119+
kubernetes.io/service-account.name: coder-v2
120+
type: kubernetes.io/service-account-token
121+
---
122+
apiVersion: rbac.authorization.k8s.io/v1
123+
kind: Role
124+
metadata:
125+
name: coder-v2
126+
rules:
127+
- apiGroups: ["", "apps", "networking.k8s.io"]
128+
resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
129+
verbs: ["create", "get", "list", "watch", "update", "patch", "delete", "deletecollection"]
130+
- apiGroups: ["metrics.k8s.io", "storage.k8s.io"]
131+
resources: ["pods", "storageclasses"]
132+
verbs: ["get", "list", "watch"]
133+
---
134+
apiVersion: rbac.authorization.k8s.io/v1
135+
kind: RoleBinding
136+
metadata:
137+
name: coder-v2
138+
subjects:
139+
- kind: ServiceAccount
140+
name: coder-v2
141+
roleRef:
142+
kind: Role
143+
name: coder-v2
144+
apiGroup: rbac.authorization.k8s.io
145+
EOF
146+
```
147+
148+
The output should be similar to:
149+
150+
```text
151+
serviceaccount/coder-v2 created
152+
secret/coder-v2 created
153+
role.rbac.authorization.k8s.io/coder-v2 created
154+
rolebinding.rbac.authorization.k8s.io/coder-v2 created
155+
```
156+
157+
### 2. Modify the Kubernetes template
158+
159+
You can start from our
160+
[example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes).
161+
162+
```hcl
163+
variable "host" {
164+
description = "Cluster host address"
165+
sensitive = true
166+
}
167+
168+
variable "cluster_ca_certificate" {
169+
description = "Cluster CA certificate (base64 encoded)"
170+
sensitive = true
171+
}
172+
173+
variable "token" {
174+
description = "Cluster CA token (base64 encoded)"
175+
sensitive = true
176+
}
177+
178+
variable "namespace" {
179+
description = "Namespace"
180+
}
181+
182+
provider "kubernetes" {
183+
host = var.host
184+
cluster_ca_certificate = base64decode(var.cluster_ca_certificate)
185+
token = base64decode(var.token)
186+
}
187+
```
188+
189+
### Create Coder template with managed variables
190+
191+
Fetch the values from the secret and pass them to Coder. This should work on
192+
macOS and Linux.
193+
194+
To get the cluster address:
195+
196+
```shell
197+
kubectl cluster-info
198+
Kubernetes control plane is running at https://example.domain:6443
199+
200+
export CLUSTER_ADDRESS=https://example.domain:6443
201+
```
202+
203+
To fetch the CA certificate and token:
204+
205+
```shell
206+
export CLUSTER_CA_CERTIFICATE=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.ca\.crt}")
207+
208+
export CLUSTER_SERVICEACCOUNT_TOKEN=$(kubectl get secrets coder-v2 -n coder-workspaces -o jsonpath="{.data.token}")
209+
```
210+
211+
Create the template with these values:
212+
213+
```shell
214+
coder templates push \
215+
--variable host=$CLUSTER_ADDRESS \
216+
--variable cluster_ca_certificate=$CLUSTER_CA_CERTIFICATE \
217+
--variable token=$CLUSTER_SERVICEACCOUNT_TOKEN \
218+
--variable namespace=coder-workspaces
219+
```
220+
221+
If you're on a Windows machine (or if one of the commands fail), try grabbing
222+
the values manually:
223+
224+
```shell
225+
# Get cluster API address
226+
kubectl cluster-info
227+
228+
# Get cluster CA and token (base64 encoded)
229+
kubectl get secrets coder-service-account-token -n coder-workspaces -o jsonpath="{.data}"
230+
231+
coder templates push \
232+
--variable host=API_ADDRESS \
233+
--variable cluster_ca_certificate=CLUSTER_CA_CERTIFICATE \
234+
--variable token=CLUSTER_SERVICEACCOUNT_TOKEN \
235+
--variable namespace=coder-workspaces
236+
```

‎docs/admin/integrations/opentofu.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Provisioning with OpenTofu
2+
3+
<!-- Keeping this in as a placeholder for supporting OpenTofu. We should fix support for custom terraform binaries ASAP. -->
4+
5+
> ⚠️ 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).
6+
7+
Coder deployments support any custom Terraform binary, including [OpenTofu](https://opentofu.org/docs/) - an open source alternative to Terraform.
8+
9+
> 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.
10+
11+
12+
13+
## Using a custom Terraform binary
14+
15+
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).
16+
17+

‎docs/admin/integrations/other.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Other platforms
2+
3+
Coder is highly extensible and is not limited to the platforms outlined in these
4+
docs. The control plane can be provisioned on any VM or container compute, and
5+
workspaces can include any Terraform resource. See our
6+
[architecture diagram](../infrastructure/architecture.md) for more details.
7+
8+
The following resources may help as you're deploying Coder.
9+
10+
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
11+
- [Deploy Coder offline](../../install/offline.md)
12+
- [Supported resources (Terraform registry)](https://registry.terraform.io)
13+
- [Writing custom templates](../templates/README.md)
14+
15+
<!-- TODO: writing custom templates link-->

0 commit comments

Comments
 (0)