Skip to content

Commit a2c6bd8

Browse files
author
Simon Emms
committed
[installer]: create readme
1 parent cb7e182 commit a2c6bd8

File tree

1 file changed

+345
-0
lines changed

1 file changed

+345
-0
lines changed

‎installer/README.md

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
<p align="center">
2+
<a href="https://www.gitpod.io">
3+
<img src="https://github.com/raw/gitpod-io/gitpod/master/components/dashboard/src/icons/gitpod.svg" height="60">
4+
<h3 align="center">Gitpod</h3>
5+
</a>
6+
<p align="center">Always ready-to-code.</p>
7+
</p>
8+
9+
# Installer
10+
11+
The best way to get started with Gitpod
12+
13+
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-908a85?logo=gitpod)](https://gitpod.io/from-referrer/)
14+
15+
# Requirements
16+
17+
- A machine running Linux/MacOS and Docker
18+
- Windows is not currently supported, but will be in future
19+
- [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) installed
20+
- A [Kubernetes cluster configured](https://www.gitpod.io/docs/self-hosted/latest/installation)
21+
22+
Or, [open a Gitpod workspace](https://gitpod.io/from-referer/)
23+
24+
The process to install Gitpod is:
25+
1. generate a base config
26+
2. amend the config for your own use-case
27+
3. validate
28+
4. render the Kubernetes YAML
29+
5. `kubectl apply`
30+
31+
# Quickstart
32+
33+
## Create a gitpod-installer script
34+
35+
```shell
36+
#!/bin/bash
37+
38+
VERSION="${VERSION:-main.1844}" # Build ID taken from https://werft.gitpod-dev.com/
39+
40+
docker run -it --rm \
41+
-v $PWD:/gitpod \
42+
-v $HOME/.kube:/root/.kube \
43+
eu.gcr.io/gitpod-core-dev/build/installer:${VERSION} \
44+
$@
45+
```
46+
47+
Save this in your `$PATH` as `gitpod-installer` and make executable
48+
49+
## Generate the base config
50+
51+
```shell
52+
gitpod-installer init > gitpod.config.yaml
53+
```
54+
55+
## Customise your config
56+
57+
There are many things you can change in your config, which can be found in
58+
the [Config Guide](#config).
59+
60+
For the purposes of a quickstart, just change the `domain` to one of your
61+
own.
62+
63+
## Validate
64+
65+
```shell
66+
# Checks the validity of the configuration YAML
67+
gitpod-installer validate config --config /gitpod/gitpod.config.yaml
68+
```
69+
70+
Any errors here must be fixed before deploying. See [Config](#config) for
71+
more details.
72+
73+
```shell
74+
# Checks that your cluster is ready to install Gitpod
75+
gitpod-installer validate cluster --kubeconfig /root/.kube/config --config /gitpod/gitpod.config.yaml
76+
```
77+
78+
Any errors here must be fixed before deploying. See [Cluster Dependencies](#cluster-dependencies)
79+
for more details.
80+
81+
## Render the YAML
82+
83+
```shell
84+
gitpod-installer render --config /gitpod/gitpod.config.yaml > gitpod.yaml
85+
```
86+
87+
## Deploy
88+
89+
```shell
90+
kubectl apply -f gitpod.yaml
91+
```
92+
93+
After a few minutes, your Gitpod installation will be available on the
94+
specified `domain`.
95+
96+
## Uninstallation
97+
98+
The Installer generates a ConfigMap with the metadata of every Kubernetes
99+
object generated by the Installer. This can be retrieved to remove Gitpod
100+
from your cluster.
101+
102+
```shell
103+
kubectl get configmaps gitpod-app -o jsonpath='{.data.app\.yaml}' \
104+
| kubectl delete -f - # Piping to this will delete automatically
105+
```
106+
107+
**Important**. This may leave certain objects still in your Kubernetes
108+
cluster. This will include `Secrets` generated from internal `Certificates`
109+
and `PersistentVolumeClaims`. These will need to be manually deleted.
110+
111+
---
112+
113+
# What is installed
114+
115+
- All Gitpod components
116+
- Container registry*
117+
- MySQL database*
118+
- Jaeger operator*
119+
- RabbitMQ
120+
- Minio object storage*
121+
122+
\* By default, these dependencies are installed if the `inCluster` setting
123+
is `true`. External dependencies can be used in their place
124+
125+
# Config
126+
127+
> Not every parameter is discussed in this table, just ones that are likely
128+
> to need changing. The full config structure is available in [config.go](/installer/pkg/config/v1/config.go).
129+
130+
| Property | Required | Description | Notes |
131+
| --- | --- | --- | --- |
132+
| `domain` | Y | The domain to deploy to | This will need to be changed on every deployment |
133+
| `kind` | Y | Installation type to run - for most users, this will be `Full` | Can be `Full`, `Meta` or `Workspace` |
134+
| `metadata.region` | Y | Location for your `objectStorage` provider | If using Minio, set to `local` |
135+
| `workspace.runtime.containerdRuntimeDir` | Y | The location of containerd on host machine | Common values are: <ul><li>`/run/containerd/io.containerd.runtime.v2.task/k8s.io` (K3s)</li><li>`/var/lib/containerd/io.containerd.runtime.v2.task/k8s.io` (AWS/GCP)</li><li>`/run/containerd/io.containerd.runtime.v1.linux/k8s.io` (Azure)</li><li>`/run/containerd/io.containerd.runtime.v1.linux/moby`</li></ul> |
136+
| `workspace.runtime.containerdSocket` | Y | The location of containerd socket on the host machine |
137+
| `workspace.runtime.fsShiftMethod` | Y | File system | Can be either `fuse` (fuse-overlayfs) or `shiftfs`. This depending upon your host OS/distribution. |
138+
139+
## Auth Providers
140+
141+
Gitpod must be connected to a Git provider. This can be done via the
142+
dashboard on first load, or by providing `authProviders` configuration.
143+
144+
```yaml
145+
authProviders:
146+
- id: Public-GitHub
147+
host: github.com
148+
type: GitHub
149+
oauth:
150+
clientId: xxx
151+
clientSecret: xxx
152+
callBackUrl: https://$DOMAIN/auth/github.com/callback
153+
settingsUrl: xxx
154+
```
155+
156+
## In-cluster vs External Dependencies
157+
158+
Gitpod requires certain services for it to function correctly. The Installer
159+
provides all of these in-cluster, but they can be configured to use services
160+
external to the cluster.
161+
162+
To use the in-cluster dependency, set `inCluster` to be `true`.
163+
164+
## Container Registry
165+
166+
```yaml
167+
containerRegistry:
168+
inCluster: false
169+
external:
170+
url: <url of registry>
171+
certificate:
172+
kind: secret
173+
name: container-registry-token
174+
```
175+
176+
The `container-registry-token` secret must contain a `.dockerconfigjson`
177+
key - this can be created by using the `kubectl create secret docker-registry`
178+
[command](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-by-providing-credentials-on-the-command-line).
179+
180+
## Database
181+
182+
Gitpod requires an instance of MySQL 5.7 for data storage.
183+
184+
The default encryption keys are `[{"name":"general","version":1,"primary":true,"material":"4uGh1q8y2DYryJwrVMHs0kWXJlqvHWWt/KJuNi04edI="}]`
185+
186+
### Google Cloud SQL Proxy
187+
188+
If using a GCP SQL instance, a [Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/sql-proxy)
189+
connection can be used.
190+
191+
```yaml
192+
database:
193+
inCluster: false
194+
cloudSQL:
195+
instance: <PROJECT_ID>:<REGION>:<INSTANCE>
196+
serviceAccount:
197+
kind: secret
198+
name: cloudsql-token
199+
```
200+
201+
The `cloudsql-token` secret must contain the following key/value pairs:
202+
- `credentials.json` - GCP Service Account key with `roles/cloudsql.client` role
203+
- `encryptionKeys` - database encryption key. Use default value as above if unsure
204+
- `password` - database password
205+
- `username` - database username
206+
207+
### External Database
208+
209+
For all other connections, use an external database configuration.
210+
211+
```yaml
212+
database:
213+
inCluster: false
214+
external:
215+
certificate:
216+
kind: secret
217+
name: database-token
218+
```
219+
220+
The `database-token` secret must contain the following key/value pairs:
221+
- `encryptionKeys` - database encryption key. Use default value as above if unsure
222+
- `host` - IP or URL of the database
223+
- `password` - database password
224+
- `port` - database port, usually `3306`
225+
- `username` - database username
226+
227+
## Object Storage
228+
229+
Gitpod supports the following object storage providers:
230+
231+
### GCP
232+
233+
```yaml
234+
objectStorage:
235+
inCluster: false
236+
cloudStorage:
237+
project: <PROJECT_ID>
238+
serviceAccount:
239+
kind: secret
240+
name: gcp-storage-token
241+
```
242+
243+
The `gcp-storage-token` secret must contain the following key/value pairs:
244+
- `service-account.json` - GCP Service Account key with `roles/storage.admin` and `roles/storage.objectAdmin` roles
245+
246+
### Azure
247+
248+
> Azure Blob Storage is not S3 compatible. This uses Minio Gateway to
249+
> provide an S3 interface
250+
251+
```yaml
252+
objectStorage:
253+
inCluster: true
254+
azure:
255+
certificate:
256+
kind: secret
257+
name: az-storage-token
258+
```
259+
260+
The `az-storage-token` secret must contain the following key/value pairs:
261+
- `accountName` - the globally-unique storage account name
262+
- `accountKey` - access key for the storage account
263+
264+
### S3
265+
266+
> Documentation coming soon [#6772](https://github.com/gitpod-io/gitpod/issues/6772)
267+
268+
# Cluster Dependencies
269+
270+
In order for the deployment to work successfully, there are certain
271+
dependencies that need to be installed.
272+
273+
## Kernel and Runtime
274+
275+
Your Kubernetes nodes must have the Linux kernel v5.4.0 or above and
276+
have a containerd runtime.
277+
278+
## Affinity Labels
279+
280+
Your Kubernetes nodes must have the following labels applied to them:
281+
- `gitpod.io/workload_meta`
282+
- `gitpod.io/workload_ide`
283+
- `gitpod.io/workload_workspace_services`
284+
- `gitpod.io/workload_workspace_regular`
285+
- `gitpod.io/workload_workspace_headless`
286+
287+
It is recommended to have a minimum of two node pools, grouping the `meta`
288+
and `ide` nodes together and the `workspace` nodes together.
289+
290+
## TLS certificates
291+
292+
It is a requirement that a certificate secret exists, named as per
293+
`certificate.name` in your config YAML with `tls.crt` and `tls.key`
294+
in the secret data. How this certificate is generated is entirely your
295+
choice - we suggest [Cert Manager](https://cert-manager.io/) for
296+
simplicity, however any certificate authority can be used by creating a
297+
Kubernetes secret.
298+
299+
The certificate must be associated with the following domains (where
300+
`$DOMAIN` is the value in config `domain`):
301+
- `$DOMAIN`
302+
- `*.$DOMAIN`
303+
- `*.ws.$DOMAIN`
304+
305+
### Cert Manager
306+
307+
Cert Manager **MUST** be installed to your cluster. In order to secure
308+
communication between the various components, the application creates
309+
internally which are created using the Cert Manager `Certificate` and
310+
`Issuer` Custom Resource Definitions.
311+
312+
```shell
313+
helm repo add jetstack https://charts.jetstack.io
314+
helm repo update
315+
helm upgrade \
316+
--atomic \
317+
--cleanup-on-fail \
318+
--create-namespace \
319+
--install \
320+
--namespace='cert-manager' \
321+
--reset-values \
322+
--set installCRDs=true \
323+
--set 'extraArgs={--dns01-recursive-nameservers-only=true,--dns01-recursive-nameservers=8.8.8.8:53\,1.1.1.1:53}' \
324+
--wait \
325+
cert-manager \
326+
jetstack/cert-manager
327+
```
328+
329+
# FAQs
330+
331+
## Why are you writing your own Installer instead of using Helm/Kustomize/etc?
332+
333+
The Installer is a complete replacement for our Helm charts. Over time,
334+
this had grown to be too complex to effectively support and was a barrier
335+
to entry for new users - the base config was many hundreds of lines long
336+
and did not have effective validation on it. By contrast, the Installer's
337+
config is < 50 lines long and can be fully validated before running.
338+
339+
# Todo
340+
341+
PRs/comments welcome
342+
343+
- [ ] [Improve distribution of gitpod-installer binaries](https://github.com/gitpod-io/gitpod/issues/6766)
344+
- [ ] [Configure and document S3 object storage](https://github.com/gitpod-io/gitpod/issues/6772)
345+
- [ ] [Create a Gitpod workspace that can be used for installing a Gitpod instance](https://github.com/gitpod-io/gitpod/issues/6801)

0 commit comments

Comments
 (0)