diff --git a/docs/self-hosted/install/configure-ingress.md b/docs/self-hosted/install/configure-ingress.md index 810bec25a5..7a9de84a61 100644 --- a/docs/self-hosted/install/configure-ingress.md +++ b/docs/self-hosted/install/configure-ingress.md @@ -11,9 +11,28 @@ There are several modes of ingress into your Gitpod installation. They mostly hi Compare [values.yaml](https://github.com/gitpod-io/gitpod/blob/master/chart/values.yaml) for details. -## Example +## IngressMode: `noDomain` + + > Custom Docker registry + For this mode to work you need to [configure a custom Docker registry](../docker-registry/) with valid HTTPS certificates. + + 1. Create a file `values.ingress.yaml` with the following content: + ``` + hostname: "123-123-123-123.ip.mygitpod.com" + ``` + Replace 123-123-123-123 with the external IP of your cluster. + + Afterwards, do an `helm upgrade --install -f values.ingress.yaml gitpod .` to apply the changes. + + > If you don't know the external IP of your cluster try running `kubectl describe svc proxy | grep -i ingress`. + + 2. Now your installation is available at `https://123-123-123-123.ip.mygitpod.com` #####TODO +## IngressMode: `pathAndHost` + +## IngressMode: `hosts` + ### Domain Gitpod requires a domain resolvable by some nameserver (typically a public domain name, e.g. `your-domain.com`). diff --git a/docs/self-hosted/install/docker-registry.md b/docs/self-hosted/install/docker-registry.md index 6d0b4d3d1e..c42c95aa5f 100644 --- a/docs/self-hosted/install/docker-registry.md +++ b/docs/self-hosted/install/docker-registry.md @@ -2,7 +2,6 @@ url: /docs/self-hosted/latest/install/docker-registry/ --- -#####TODO # Docker Registry Gitpod builds Docker images during workspace startup. This enables custom Dockerfiles as part of your workspace config, but is also required for Gitpod itself to function. @@ -14,20 +13,60 @@ By default Gitpod ships with a built-in Docker registry. If you operate your own The docker registry requires a Kubernetes PersistentVolume. This registry is not recommended to be used for production. * Own docker registry: Gitpod can connect to your own docker registry. Compared to its built-in counterpart this enables performance gains and access to otherwise private images. -This helm chart can either deploy its own registry (default but requires [HTTPS certs](../https-certs/)) or use an existing one. -To connect to an existing Docker registry, do the following steps: +This helm chart can either deploy its own registry (default but requires [HTTPS certs](../configures-ingress/)) or use an existing one. -``` -echo values/registry.yaml >> configuration.txt -``` +## Configuration +To connect to an existing Docker registry, perform the following steps: -In `values/registry.yaml` replace `your.registry.com` with the name of your registry. + 1. Create a file `values.docker-registry.yaml` containing: + ``` + components: + imageBuilder: + registryCerts: [] + registry: + # name must not end with a "/" + name: eu.gcr.io/gpl-sh-kubeup-2 + secretName: image-builder-registry-secret + path: secrets/registry-auth.json -Login to the registry and safe the authentication -``` -docker --config secrets/ login your.registry.com && mv secrets/config.json secrets/registry-auth.json -``` + workspace: + pullSecret: + secretName: image-builder-registry-secret -Make sure the resulting JSON file contains the credentials (there should be an `auth` section containing them as base64 encoded string). + docker-registry: + enabled: false + ``` + Replace `your.registry.com/gitpod` with the domain your registry is available at. + + 2. Login to the registry and safe the authentication + ``` + mkdir -p secrets + docker login your.registry.com/gitpod && cp ~/.docker/config.json secrets/registry-auth.json + ``` + + > This does not work for Google Cloud Registries because their login tokens are short-lived. See the [example](#example-google-cloud-registry-credentials) below on how to configure it. + + 3. Do a `helm upgrade --install -f values.docker-registry.yaml gitpod .` to apply the changes. + +Make sure the resulting JSON file contains the credentials (there should be an `auths` section containing them as base64 encoded string). If that's not the case you might have a credential store/helper set up (e.g. on macOS the _Securely store Docker logins in macOS keychain_ setting). + +### Example Google Cloud Registry Credentials + + Prerequisites: + - `gcloud` [installed](https://cloud.google.com/sdk/docs/quickstart) and [authenticated](https://cloud.google.com/sdk/gcloud/reference/auth/login) + +How to use Google Cloud Registry as Docker registry for Gitpod: + 1. Go to [https://console.cloud.google.com/gcr/images/\?project=\](https://console.cloud.google.com/gcr/images/\?project=\) and hit "Enable Registry API" (if not already enabled). + + 1. Execute the following commands: + ``` + export PROJECT_ID="" + + gcloud iam service-accounts create gitpod-registry-full --project=$PROJECT_ID + gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:gitpod-registry-full@$PROJECT_ID.iam.gserviceaccount.com" --role=roles/storage.admin + gcloud iam service-accounts keys create gitpod-registry-full-key.json --iam-account=gitpod-registry-full@$PROJECT_ID.iam.gserviceaccount.com + + echo "{\"auths\":{\"gcr.io\": {\"auth\": \"$(echo -n "$(echo -n "_json_key:"; cat gitpod-registry-full-key.json)" | base64 -w 0)\"}}}" > secrets/registry-auth.json + ``` \ No newline at end of file diff --git a/docs/self-hosted/install/install-on-kubernetes.md b/docs/self-hosted/install/install-on-kubernetes.md index b18e944928..1c90ae6dda 100644 --- a/docs/self-hosted/install/install-on-kubernetes.md +++ b/docs/self-hosted/install/install-on-kubernetes.md @@ -13,7 +13,7 @@ Gitpod is installed using [Helm](https://helm.sh). The chart can be found [here] ## Installation -To perform the installation run the following commands: +To initiate the deployment run the following commands: ```console git clone https://github.com/gitpod-io/gitpod @@ -23,16 +23,27 @@ helm repo add charts.gitpod.io https://charts.gitpod.io helm repo add stable https://charts.helm.sh/stable helm repo add stable https://helm.min.io/ helm repo update +helm dep up -helm upgrade --install $(for i in $(cat configuration.txt); do echo -e "-f $i"; done) gitpod . +helm install gitpod . ``` -#####TODO + + > Review the deployment worked properly by running `kubectl get pods`. Eventually all pods should be up-and-running. In case they are not have a look the the [Troubleshooting Guide](./troubleshooting.md) + + 1. Configure [ingress into the cluster](../configure-ingress/) + + 2. Go to https://123-123-123-123.ip.mygitpod.com/workspace and follow the steps to setup OAuth + ## Recommended Configuration - +Without further configuration the Helm chart installs a working Gitpod installation in a lot of scenarios. +Yet, there are certain things you want to review when installing Gitpod for long term use or a bigger audience: +* [**Database**](../database/): Configure where Gitpod stores all internal runtime data. +* [**Storage**](../storage/): Configure where Gitpod persists workspace content. +* [**Docker Registry**](../docker-registry/): Configure where Gitpod stores workspace images that are build at runtime. ## Customization -* [**Storage**](../storage/): Configure where Gitpod stores stopped workspaces. +Further customizations: * [**Kubernetes Nodes**](../nodes/): Configure file system layout and the workspace's node associativity. * [**Workspaces**](../workspaces/): Configure workspace sizing.