{"id":20670075,"url":"https://github.com/gitpod-io/gitpod-microsoft-aks-guide","last_synced_at":"2025-04-19T18:13:51.945Z","repository":{"id":38195800,"uuid":"399740789","full_name":"gitpod-io/gitpod-microsoft-aks-guide","owner":"gitpod-io","description":"Running Gitpod in Azure AKS ","archived":false,"fork":false,"pushed_at":"2022-08-24T09:50:49.000Z","size":153,"stargazers_count":20,"open_issues_count":0,"forks_count":20,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-29T11:34:34.085Z","etag":null,"topics":["azure","azure-kubernetes-service","gitpod","gitpod-self-hosted","kubernetes"],"latest_commit_sha":null,"homepage":"","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-08-25T08:11:40.000Z","updated_at":"2024-07-09T03:27:27.000Z","dependencies_parsed_at":"2023-01-16T18:01:10.627Z","dependency_job_id":null,"html_url":"https://github.com/gitpod-io/gitpod-microsoft-aks-guide","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-microsoft-aks-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-microsoft-aks-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-microsoft-aks-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitpod-io%2Fgitpod-microsoft-aks-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitpod-io","download_url":"https://codeload.github.com/gitpod-io/gitpod-microsoft-aks-guide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249760378,"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":["azure","azure-kubernetes-service","gitpod","gitpod-self-hosted","kubernetes"],"created_at":"2024-11-16T20:17:53.776Z","updated_at":"2025-04-19T18:13:51.927Z","avatar_url":"https://github.com/gitpod-io.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Running Gitpod in [Azure AKS](https://azure.microsoft.com/en-gb/services/kubernetes-service/)\n\n\u003e **IMPORTANT** This guide exists as a simple and reliable way of creating an environment in AKS that can run Gitpod. It 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\nBefore starting the installation process, you need:\n\n- An Azure account\n  - [Create one now by clicking here](https://azure.microsoft.com/en-gb/free/)\n- A user account with \"Owner\" IAM rights on the subscription\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## Azure authentication\n\nFor simplicity, this guide does **not** use an Azure [service principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal).\nAuthentication is done via an interactive URL, similar to this:\n\n```shell\nTo sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABC123DEF to authenticate.\n```\n\n**To start the installation, execute:**\n\n```shell\nmake install\n```\n\nThe whole process takes around twenty minutes. In the end, the following resources are created. These are the Azure versions of the [components Gitpod requires](https://www.gitpod.io/docs/self-hosted/latest/required-components):\n\n- an AKS cluster running Kubernetes v1.21.\n- Azure load balancer.\n- Azure MySQL database.\n- Azure Blob Storage.\n- Azure DNS zone.\n- Azure container registry.\n- [calico](https://docs.projectcalico.org) as CNI and NetworkPolicy implementation.\n- [cert-manager](https://cert-manager.io/) for self-signed SSL certificates.\n\nUpon 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). **IMPORTANT** - running the `make install` command after the initial install will change \nyour database password which will require you to update your KOTS configuration.\n\n## DNS records\n\n\u003e This setup will work even if the parent domain is not owned by a DNS zone in the Azure portal.\n\nThe recommended setup is to have `SETUP_MANAGED_DNS` be `true` which will create an\n[Azure DNS zone](https://docs.microsoft.com/en-us/azure/dns/dns-zones-records) for your\ndomain. When the zone is created, you will see various nameserver records (with type `NS`), such\nas `ns1-xx.azure-dns.com`, `ns2-xx.azure-dns.net`, `ns3-xx.azure-dns.org` and `ns4-xx.azure-dns.info`\n(where `xx` is the number randomly assigned by Azure).\n\nIn the DNS manager for the parent domain (eg, `example.com`), create a nameserver record for\neach of the nameservers generated by Azure under the subdomain used (eg, `gitpod.example.com`).\nThis is what it would look like if your parent domain was using Cloudflare.\n\n![Cloudflare DNS manager](./images/dns-record.png \"Cloudflare DNS manager\")\n\nOnce applied, please allow a few minutes for DNS propagation.\n\n### Common errors running make install\n\n- Insufficient regional quota to satisfy request\n\n  Depending on the size of the configured `disks size` and `machine-type`,\n  it may be necessary to request an [increase in the service quota](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)\n\n  *After increasing the quota, retry the installation running `make install`*\n\n- Some pods never start (`Init` state)\n\n  ```shell\n  kubectl get pods -l component=proxy\n  NAME                     READY   STATUS    RESTARTS   AGE\n  proxy-5998488f4c-t8vkh   0/1     Init 0/1  0          5m\n  ```\n\n  The most likely reason is that the [DNS01 challenge](https://cert-manager.io/docs/configuration/acme/dns01/) has yet to resolve. If using `SETUP_MANAGED_DNS`, you will need to update your DNS records to point to the Azure DNS zone nameserver.\n\n  Once the DNS record has been updated, you will need to delete all cert-manager pods to retrigger the certificate request\n\n  ```shell\n  kubectl delete pods -n cert-manager --all\n  ```\n\n  After a few minutes, you should see the `https-certificate` become ready.\n\n  ```shell\n  kubectl get certificate\n  NAME                        READY   SECRET                      AGE\n  https-certificates          True    https-certificates          5m\n  ```\n\n## Destroy the cluster and Azure resources\n\nRemove the Azure cluster running:\n\n```shell\nmake uninstall\n```\n\n\u003e The command asks for confirmation:\n\u003e `Are you sure you want to delete: Gitpod (y/n)?`\n\nThis will destroy the Kubernetes cluster and allow you to manually delete the cloud storage.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitpod-io%2Fgitpod-microsoft-aks-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitpod-io%2Fgitpod-microsoft-aks-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitpod-io%2Fgitpod-microsoft-aks-guide/lists"}