Configure the ingress to your Gitpod installation
⚠️ Deprecated Content
The content of this page assumes you are using Helm, which is now deprecated. Please use the Installer instead.
Configuring ingress into your Gitpod installation requires two things:
- three DNS entries pointing at the IP of Gitpod’s proxy service, and
- HTTPS certificates.
1. DNS Entries
Gitpod requires a domain resolvable by some nameserver (typically a public domain name, e.g.
As Gitpod launches services and workspaces on additional subdomains it also needs two wildcard domains.
your-domain.com .your-domain.com .ws.your-domain.com
Installing Gitpod on a subdomain works as well. For example:
gitpod.your-domain.com .gitpod.your-domain.com .ws.gitpod.your-domain.com
Arecords for all three (sub)domains. To learn your installation’s IP run:language:bash
kubectl describe svc proxy | grep -i ingress
Merge the following into your
hostname: your-domain.com components: proxy: loadBalancerIP: <your-IP>
loadBalancerIPmake sure it stays the same across all redeploys.
Gitpod requires HTTPS certificates to function properly. We recommend using Let’s Encrypt for retrieving certificates as we do for gitpod.io.
Important: The HTTPS certificates for your domain must include
*.ws.your-domain.com. Beware that wildcard certificates are valid for one level only (i.e.
*.a.comis not valid for
To configure the HTTPS certificates for your domain
- Generate certificates and put your certificate files under
secrets/https-certificates: |- tls.crt |- tls.key
- Generate the dhparams.pem file using:language:bash
openssl dhparam -out secrets/https-certificates/dhparams.pem 2048
- Create a kubernetes secret using:language:bash
kubectl create secret generic https-certificates --from-file=secrets/https-certificates
- Afterwards, do an
helm upgrade --install -f values.custom.yaml gitpod gitpod.io/gitpod --version=0.10.0to apply the changes.
Using Let’s Encrypt to generate HTTPS certificates
The most accessible means of obtaining HTTPS certificates is using Let’s Encrypt. It provides free certificates to anybody who can prove ownership of a domain. Let’s Encrypt offers a program called certbot to make acquiring certificates as straightforward as possible.
Assuming you have certbot installed, the following script will generate and configure the required certificates (notice the placeholders):
export DOMAIN=your-domain.com export EMAILemail@example.com export WORKDIR=$PWD/letsencrypt certbot certonly \ --config-dir $WORKDIR/config \ --work-dir $WORKDIR/work \ --logs-dir $WORKDIR/logs \ --manual \ --preferred-challenges=dns \ --email $EMAIL \ --server https://acme-v02.api.letsencrypt.org/directory \ --agree-tos \ -d *.ws.$DOMAIN \ -d *.$DOMAIN \ -d $DOMAIN # move them into place mkdir -p secrets/https-certificates cp $WORKDIR/config/live/fullchain.pem secrets/https-certificates/tls.crt cp $WORKDIR/config/live/privkey.pem secrets/https-certificates/tls.key
Note: Do not refrain if
certbotfails on first execution: Depending on the challenge used you might have to restart it once.