{"id":18390134,"url":"https://github.com/elafarge/karch","last_synced_at":"2025-04-07T02:35:03.254Z","repository":{"id":24446054,"uuid":"101583980","full_name":"elafarge/karch","owner":"elafarge","description":"A Terraform module to create and maintain Kubernetes clusters on AWS easily, relying entirely on kops","archived":false,"fork":false,"pushed_at":"2023-01-26T11:34:06.000Z","size":152,"stargazers_count":38,"open_issues_count":1,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-22T11:51:11.793Z","etag":null,"topics":["aws","containers","infrastructure-as-code","karch","kops","kubernetes-cluster","terraform"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elafarge.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-08-27T22:24:16.000Z","updated_at":"2023-01-05T19:34:04.000Z","dependencies_parsed_at":"2023-02-14T17:01:10.287Z","dependency_job_id":null,"html_url":"https://github.com/elafarge/karch","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elafarge%2Fkarch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elafarge%2Fkarch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elafarge%2Fkarch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elafarge%2Fkarch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elafarge","download_url":"https://codeload.github.com/elafarge/karch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247583639,"owners_count":20962063,"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","containers","infrastructure-as-code","karch","kops","kubernetes-cluster","terraform"],"created_at":"2024-11-06T01:46:23.181Z","updated_at":"2025-04-07T02:34:58.246Z","avatar_url":"https://github.com/elafarge.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"karch - A terraform module to spawn Kubernetes clusters\n=======================================================\n\n`karch` is a Terraform module based on\n[kops](https://github.com/kubernetes/kops) aiming at managing (multiple)\nKubernetes clusters on AWS. You can see it as \"Terraform bindings for kops\".\n\nIt essentially aims at making it easier to share Kubernetes cluster topologies\nor even entire stacks built atop Kubernetes.\n\nMotivations\n-----------\n`kops` has become the standard, non-opinionated way of deploying Kubernetes\nclusters on AWS and can even generate Terraform code. However, this approach has\nsome limits:\n * Values of resources managed by `kops`, such as the id of the cluster's VPC,\n   subnets, etc... aren't really accessible from the rest of your codebase.\n * One needs one subfolder per cluster (which can be used as a Terraform\n   module): creating a \"cluster template\" (masters + several IGs) that can\n   easily be replicated accross AWS regions \u0026 shared accross teams isn't\n   possible\n\nIt seemed that wrapping by wrapping the `kops` CLI itself into a Terraform\nmodule whicch really feels like a simple Terraform module could fulfill this\nneed for portable, reapeatable infrastructure a bit better. Of course, keeping\nthe flexibilty offered by `kops`'s cluster \u0026 instance group spec available by\nexposing all the parameters it provides as Terraform variables felt essential.\n\nTherfore, `karch` aims at making it easy to encode Kubernetes cluster topologies\nusing Terraform infrastructure code. For instance, such a topology could be:\n - an instance group for a pool of NginX ingress controllers, mounting ports\n - one for your backend APIs\n - one for stateful apps (databases, data stores...)\n - one, with GPU instances, to run your ML pipeline\n - with Kubernetes to orchestrate all types of workloads\n\nWhat `karch` is\n---------------\n * A Terraform library, written in plain HCL and using essentially `kops`, `sh`\n   and `awk`.\n * A set of two Terraform modules `cluster` and `ig`. The former spaws a base\n   cluster, in a new VPC, the latter can be used to spawn instance groups.\n * A wrapper around `kops`, instead of using `kops` directly, you'll be using\n   a terraform module to create/update/delete your `kops` clusters. When\n   necessary, this module will take care of rolling out your instance groups.\n\nWhat `karch` isn't\n------------------\n * A Terraform provider **plugin**. Writing such a plugin would be nice, but\n   would require much more time to implement.\n * For now, `karch` spawns only clusters with a `private` topology. Adding the\n   ability to create `public` clusters will come next\n * For now, `karch` takes care of creating a VPC and Route53 zone for your\n   cluster's subdomain. Being able to give it an already existing VPC and/or\n   zone is on the roadmap\n\nGetting started\n---------------\n#### Requirements\nYou'll only need `kops`, `kubectl`, `sh`, and the `aws-cli` (or at\nleast, an AWS account configured `accordingly` under `~/.aws/credentials`).\n\n#### Creating a Kubernetes cluster\n\nTo create a Kubernetes cluster, you can use the `kops-cluster` module:\nYou can refer to `./kops-cluster/variables.tf` for a documented list of all the\nvariables you can pass to the module.\n```\nmodule \"kops-cluster\" {\n  source  = \"github.com/elafarge/karch/aws/cluster\"\n  version = \"1.7.1\"\n\n  aws-region              = \"eu-west-1\"\n\n  # Networking \u0026 connectivity\n  vpc-name                  = \"kube-hq\"\n  vpc-cidr                  = \"10.70.0.0/16\"\n  availability-zones        = [\"eu-west-1a\", \"eu-west-1b\", \"eu-west-1c\"]\n  kops-topology             = \"private\"\n  trusted-cidrs             = \"0.0.0.0/0\"\n  admin-ssh-public-key-path = \"~/.ssh/id_rsa.pub\"\n\n  # DNS\n  main-zone-id    = \"example.com\"\n  cluster-name    = \"kube-hq.example.com\"\n\n  # Kops \u0026 Kuberntetes\n  kops-state-bucket  = \"example-com-kops-state\"\n\n  # Master\n  master-availability-zones = [\"eu-west-1a\"]\n  master-image              = \"ami-109d6069\"\n\n  # Bastion\n  bastion-image        = \"ami-109d6069\"\n\n  # First minion instance group\n  minion-image        = \"ami-109d6069\"\n}\n```\n\n#### Adding instance groups to the cluster\n\nHere as well, it boils down to simply using a Terraform module. The list of\naccepted variables can be found under `./kops-ig/variables.tf`.\n```\nmodule \"ingress-ig\" {\n  source  = \"github.com/elafarge/karch/aws/ig\"\n  version = \"1.7.1\"\n\n  aws-region              = \"eu-west-1\"\n\n  # Master cluster dependency hook\n  master-up = \"${module.kops-cluster.master-up}\"\n\n  # Global config\n  name              = \"ingress\"\n  cluster-name      = \"kube-hq.example.com\"\n  kops-state-bucket = \"example-com-kops-state\"\n  visibility        = \"private\"\n  subnets           = [\"eu-west-1a\", \"eu-west-1b\", \"eu-west-1c\"]\n  image             = \"ami-109d6069\"\n  type              = \"t2.small\"\n  volume-size       = \"16\"\n  volume-type       = \"gp2\"\n  min-size          = 2\n  max-size          = 3\n  node-labels       = \"${map(\"role.node\", \"ingress\")}\"\n}\n```\n\n#### Mainting your cluster\nYou can entirely rely on Terraform to update your cluster on `terraform apply`.\nPlease note that we never run `kops rolling-update` for cluster updates. You'll\nneed to run it manually. However, rolling updates can be automatically applied\nfor instance groups, with a configurable node rollout time interval.\n\nMaintainers\n-----------\n * Étienne Lafarge \u003cetienne.lafarge _at_ gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felafarge%2Fkarch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felafarge%2Fkarch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felafarge%2Fkarch/lists"}