Skip to content

Commit 955a166

Browse files
bpmctbpmct
committed
kubernetes example
1 parent 563d99d commit 955a166

File tree

1 file changed

+22
-111
lines changed

1 file changed

+22
-111
lines changed

‎examples/templates/kubernetes/README.md

Lines changed: 22 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,38 @@
11
---
2-
name: Develop in Kubernetes
3-
description: Get started with Kubernetes development.
4-
tags: [cloud, kubernetes]
5-
icon: /icon/k8s.png
2+
display_name: Kubernetes
3+
description: Develop inside a Kubernetes Pod
4+
icon: /icons/k8s.png
5+
maintainer_github: coder
6+
verified: true
7+
tags: [kubernetes, container]
68
---
79

8-
# Getting started
10+
# Remote Development on Kubernetes Pods
911

10-
This template creates a deployment running the `codercom/enterprise-base:ubuntu` image.
12+
Provision Kubernetes Pods as [Coder workspaces](https://coder.com/docs/coder-v2/latest) with this example template.
1113

12-
## Prerequisites
13-
14-
This template uses [`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 deploymnets. For example if you are using [helm](https://coder.com/docs/v2/latest/install/kubernetes#install-coder-with-helm) to install Coder, you should set `coder.serviceAccount.enableDeployments=true` in your `values.yaml`
15-
16-
```diff
17-
coder:
18-
serviceAccount:
19-
workspacePerms: true
20-
- enableDeployments: false
21-
+ enableDeployments: true
22-
annotations: {}
23-
name: coder
24-
```
25-
26-
> Note: This is only required for Coder versions < 0.28.0, as this will be the default value for Coder versions >= 0.28.0
27-
28-
## Authentication
29-
30-
This template can authenticate using in-cluster authentication, or using a kubeconfig local to the
31-
Coder host. For additional authentication options, consult the [Kubernetes provider
32-
documentation](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs).
33-
34-
### kubeconfig on Coder host
35-
36-
If the Coder host has a local `~/.kube/config`, you can use this to authenticate
37-
with Coder. Make sure this is done with same user that's running the `coder` service.
38-
39-
To use this authentication, set the parameter `use_kubeconfig` to true.
40-
41-
### In-cluster authentication
42-
43-
If the Coder host runs in a Pod on the same Kubernetes cluster as you are creating workspaces in,
44-
you can use in-cluster authentication.
14+
<!-- TODO: Add screenshot -->
4515

46-
To use this authentication, set the parameter `use_kubeconfig` to false.
47-
48-
The Terraform provisioner will automatically use the service account associated with the pod to
49-
authenticate to Kubernetes. Be sure to bind a [role with appropriate permission](#rbac) to the
50-
service account. For example, assuming the Coder host runs in the same namespace as you intend
51-
to create workspaces:
52-
53-
```yaml
54-
apiVersion: v1
55-
kind: ServiceAccount
56-
metadata:
57-
name: coder
58-
59-
---
60-
apiVersion: rbac.authorization.k8s.io/v1
61-
kind: RoleBinding
62-
metadata:
63-
name: coder
64-
subjects:
65-
- kind: ServiceAccount
66-
name: coder
67-
roleRef:
68-
kind: Role
69-
name: coder
70-
apiGroup: rbac.authorization.k8s.io
71-
```
72-
73-
Then start the Coder host with `serviceAccountName: coder` in the pod spec.
74-
75-
### Authenticate against external clusters
76-
77-
You may want to deploy workspaces on a cluster outside of the Coder control plane. Refer to the [Coder docs](https://coder.com/docs/v2/latest/platforms/kubernetes/additional-clusters) to learn how to modify your template to authenticate against external clusters.
78-
79-
## Namespace
80-
81-
The target namespace in which the deployment will be deployed is defined via the `coder_workspace`
82-
variable. The namespace must exist prior to creating workspaces.
83-
84-
## Persistence
16+
## Prerequisites
8517

86-
The `/home/coder` directory in this example is persisted via the attached PersistentVolumeClaim.
87-
Any data saved outside of this directory will be wiped when the workspace stops.
18+
### Infrastructure
8819

89-
Since most binary installations and environment configurations live outside of
90-
the `/home` directory, we suggest including these in the `startup_script` argument
91-
of the `coder_agent` resource block, which will run each time the workspace starts up.
20+
**Cluster**: This template requires an existing Kubernetes cluster
9221

93-
For example, when installing the `aws` CLI, the install script will place the
94-
`aws` binary in `/usr/local/bin/aws`. To ensure the `aws` CLI is persisted across
95-
workspace starts/stops, include the following code in the `coder_agent` resource
96-
block of your workspace template:
22+
**Container Image**: This template uses the [codercom/enterprise-base:ubuntu image](https://github.com/coder/enterprise-images/tree/main/images/base) with some dev tools preinstalled. To add additional tools, extend this image or build it yourself.
9723

98-
```terraform
99-
resource "coder_agent" "main" {
100-
startup_script = <<-EOT
101-
set -e
102-
# install AWS CLI
103-
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
104-
unzip awscliv2.zip
105-
sudo ./aws/install
106-
EOT
107-
}
108-
```
24+
### Authentication
10925

110-
## code-server
26+
This template authenticates using a `~/.kube/config`, if present on the server, or via built-in authentication if the Coder provisioner is running on Kubernetes with an authorized ServiceAccount. To use another [authentication method](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication), edit the template.
11127

112-
`code-server` is installed via the `startup_script` argument in the `coder_agent`
113-
resource block. The `coder_app` resource is defined to access `code-server` through
114-
the dashboard UI over `localhost:13337`.
28+
## Architecture
11529

116-
## Deployment logs
30+
> **Note**
31+
> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
11732
118-
To stream kubernetes pods events from the deployment, you can use Coder's [`coder-logstream-kube`](https://github.com/coder/coder-logstream-kube) tool. This can stream logs from the deployment to Coder's workspace startup logs. You just need to install the `coder-logstream-kube` helm chart on the cluster where the deployment is running.
33+
This template provisions the following resources:
11934

120-
```shell
121-
helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
122-
helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
123-
--namespace coder \
124-
--set url=<your-coder-url-including-http-or-https>
125-
```
35+
- Kubernetes pod (ephemeral)
36+
- Kubernetes persistent volume claim (persistent on `/home/coder`)
12637

127-
For detailed instructions, see [Deployment logs](https://coder.com/docs/v2/latest/platforms/kubernetes/deployment-logs)
38+
This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/v2/latest/dotfiles) their workspaces with dotfiles.

0 commit comments

Comments
 (0)