{"id":20670105,"url":"https://github.com/gitpod-io/gitpod-eks-guide","last_synced_at":"2025-04-19T18:14:01.301Z","repository":{"id":40431386,"uuid":"381723997","full_name":"gitpod-io/gitpod-eks-guide","owner":"gitpod-io","description":"This repo is being deprecated in favor of the single cluster reference architecture and the corresponding Terraform config.","archived":false,"fork":false,"pushed_at":"2022-09-06T11:00:53.000Z","size":601,"stargazers_count":51,"open_issues_count":0,"forks_count":18,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-29T11:34:34.791Z","etag":null,"topics":["aws-eks","gitpod","self-hosted"],"latest_commit_sha":null,"homepage":"https://www.gitpod.io/docs/configure/self-hosted/latest/reference-architecture/single-cluster-ref-arch","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gitpod-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-30T14:08:32.000Z","updated_at":"2024-07-17T18:37:09.000Z","dependencies_parsed_at":"2022-09-19T03:20:40.293Z","dependency_job_id":null,"html_url":"https://github.com/gitpod-io/gitpod-eks-guide","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-eks-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-eks-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-eks-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-eks-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitpod-io","download_url":"https://codeload.github.com/gitpod-io/gitpod-eks-guide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249760407,"owners_count":21321844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-eks","gitpod","self-hosted"],"created_at":"2024-11-16T20:18:03.351Z","updated_at":"2025-04-19T18:14:01.282Z","avatar_url":"https://github.com/gitpod-io.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n ## 📣 [IMPORTANT] This repo is being deprecated in favor of the [single cluster reference architecture](https://www.gitpod.io/docs/self-hosted/latest/reference-architecture/single-cluster-ref-arch) and the corresponding [Terraform config](https://github.com/gitpod-io/gitpod/tree/main/install/infra/single-cluster/aws).\n\n**What?** \n\nWe are deprecating this guide in favor of our [reference architectures](https://www.gitpod.io/docs/self-hosted/latest/reference-architecture) (specifically the [single cluster variant](https://www.gitpod.io/docs/self-hosted/latest/reference-architecture/single-cluster-ref-arch)) that include both a guided walk-through and a `Terraform` configuration.\n\n**Why?**\n\nFrom your feedback, we’ve learned that the guide has several shortcomings:\n\n- It is not obvious what the guide does: it is more a black box than a sensible starting point for creating the infrastructure that works for you.\n- One size fits all: it was not flexible enough if you wish to customize the infrastructure being created.\n- No incremental upgrades: If a version of a component changes, you’d have to recreate the infrastructure.\n\nDue to the feedback above we’ve decided to move to a more open and industry-standard way of speaking about the recommended infrastructure in the form of our new [reference architectures](https://www.gitpod.io/docs/self-hosted/latest/reference-architecture/single-cluster-ref-arch). These are descriptions of what the ideal infrastructure for Gitpod looks like depending on your circumstances. They include both a text version as well as a Terraform configuration that helps you create this infrastructure automatically - similarly to this guide. We believe these provide the following benefits: \n\n- They are based on a popular `Infrastructure as Code (IaC)` solution (`Terraform`), which should facilitate maintenance for you (and us) via features such as incremental upgrades.\n- They are easier to parse, as they are configuration files rather than a script. This should make customizations easier.\n- They provide a detailed walkthrough for those that do not want to use Terraform.\n- We already leverage these in our nightly testing to provide further validation and reliability of them when used to run Gitpod.\n\n**Impact?**\n\nGoing forward, Gitpod will only officially support the [reference architectures](https://www.gitpod.io/docs/self-hosted/latest/reference-architecture/single-cluster-ref-arch). If you can, we would advise you to switch towards using these - this would require you to recreate your infrastructure using the new Terraform configurations or guide. Staying on infrastructure created by this guide *should* work going forward, however, we cannot guarantee this in perpetuity.\n\n—\u003e The Reference Architectures are still in `beta` or `alpha` while we gather more feedback. Please do reach out to us on Discord or via [support](https://www.gitpod.io/support) with any problems or feedback.\n\n------\n## Running Gitpod in [Amazon EKS](https://aws.amazon.com/en/eks/)\n\n\u003e **IMPORTANT** This guide exists as a simple and reliable way of creating required AWS infrastructure. It\n\u003e is not designed to cater for every situation. If you find that it does not meet your exact needs,\n\u003e please fork this guide and amend it to your own needs.\n\nThis guide exists as a simple and reliable way of creating an environment in AWS (EKS) that [Gitpod can\nbe installed](https://www.gitpod.io/docs/self-hosted/latest/getting-started#step-4-install-gitpod) into. Upon completion, it will print the config for the resources created (including passwords) and create the necessary credential files that will allow you to connect the components created to your Gitpod instance during the [next installation step](https://www.gitpod.io/docs/self-hosted/latest/getting-started#step-4-install-gitpod).\n\n### Provision an EKS cluster\n\nBefore starting the installation process, you need:\n\n- An AWS account with Administrator access\n  - [Create one now by clicking here](https://aws.amazon.com/getting-started/)\n- AWS credentials set up. By default, those configs are present in `$HOME/.aws/`.\n- [eksctl](https://eksctl.io/) config file describing the cluster.\n  - Here is an [eks-cluster.yaml](eks-cluster.yaml) you can use as example.\n- A `.env` file with basic details about the environment.\n  - We provide an example of such file [here](.env.example).\n- [Docker](https://docs.docker.com/engine/install/) installed on your machine, or better, a Gitpod workspace :)\n\n### SSL Certificate\n\nCreate a public SSL/TLS certificate with [AWS Certificate Manager](https://aws.amazon.com/en/certificate-manager/),\nvalid for the `\u003cdomain\u003e`, `*.ws.\u003cdomain\u003e` and `*.\u003cdomain\u003e` Domain names.\n\nOnce the certificate is issued and verified, Update the `CERTIFICATE_ARN` field in the `.env` file accordingly.\n\n### Choose an Amazon Machine Image (AMI)\n\nPlease update the `ami` field in the [eks-cluster.yaml](eks-cluster.yaml) file with the proper AMI ID for the region of the cluster.\n\n| Region       | AMI                   |\n| ------------ | --------------------- |\n| us-west-1    | ami-04e9afc0a981cac90 |\n| us-west-2    | ami-009935ddbb32a7f3c |\n| eu-west-1    | ami-0f08b4b1a4fd3ebe3 |\n| eu-west-2    | ami-05f027fd3d0187541 |\n| eu-central-1 | ami-04a8127c830f27712 |\n| us-east-1    | ami-076db8ca29c04327b |\n| us-east-2    | ami-0ad574da759c55c17 |\n\n**To start the installation, execute:**\n\n```shell\nmake install\n```\n\n**Important: DNS propagation can take several minutes until the configured domain is available!**\n\nThe whole process takes around forty minutes. In the end, the following resources are created:\n\n- an EKS cluster running Kubernetes v1.21\n- Kubernetes nodes using a custom [AMI image](https://github.com/gitpod-io/amazon-eks-custom-amis/tree/gitpod):\n  - Ubuntu 21.10\n  - Linux kernel v5.13\n  - containerd v1.5.8\n  - runc: v1.0.1\n  - CNI plugins: v0.9.1\n  - Stargz Snapshotter: v0.10.0\n\n- ALB load balancer with TLS termination and re-encryption\n- RDS Mysql database\n- Two autoscaling groups, one for gitpod components and another for workspaces\n- In-cluster docker registry using S3 as storage backend\n- IAM account with S3 access (docker-registry and gitpod user content)\n- [calico](https://docs.projectcalico.org) as CNI and NetworkPolicy implementation\n- [cert-manager](https://cert-manager.io/) for self-signed SSL certificates\n- [cluster-autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler)\n- [Jaeger operator](https://github.com/jaegertracing/helm-charts/tree/main/charts/jaeger-operator) - and Jaeger deployment for gitpod distributed tracing\n- [metrics-server](https://github.com/kubernetes-sigs/metrics-server)\n- A public DNS zone managed by Route53 (if `ROUTE53_ZONEID` env variable is configured)\n\n\n## Update Gitpod auth providers\n\nPlease check the [OAuth providers integration documentation](https://www.gitpod.io/docs/self-hosted/latest/configuration/authentication) expected format.\n\nWe provide an [example here](./auth-providers-patch.yaml). Fill it with your OAuth providers data.\n\n```console\nmake auth\n```\n\n\u003e We are aware of the limitation of this approach, and we are working to improve the helm chart to avoid this step.\n\n## Destroy the cluster and AWS resources\n\nRemove Cloudformation stacks and EKS cluster running:\n\n```shell\nmake uninstall\n```\n\n\u003e The command asks for a confirmation:\n\u003e `Are you sure you want to delete: Gitpod, Services/Registry, Services/RDS, Services, Addons, Setup (y/n)?`\n\n\u003e Please make sure you delete the S3 bucket used to store the docker registry images!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitpod-io%2Fgitpod-eks-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitpod-io%2Fgitpod-eks-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitpod-io%2Fgitpod-eks-guide/lists"}