{"id":19482525,"url":"https://github.com/git-ogawa/setup_kube_cluster","last_synced_at":"2026-06-16T15:31:42.594Z","repository":{"id":55765727,"uuid":"522955186","full_name":"git-ogawa/setup_kube_cluster","owner":"git-ogawa","description":"Ansible playbooks to create k8s cluster for development on cloud  such as AWS EC2 or on local VMs","archived":false,"fork":false,"pushed_at":"2025-04-19T07:08:19.000Z","size":205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T13:43:01.181Z","etag":null,"topics":["ansible","ansible-playbook","ec2-instance","kubernetes-cluster"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-ogawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-09T13:10:39.000Z","updated_at":"2025-04-19T07:06:55.000Z","dependencies_parsed_at":"2023-01-19T16:03:46.153Z","dependency_job_id":"33944253-97cc-489c-86e0-7409766db1a9","html_url":"https://github.com/git-ogawa/setup_kube_cluster","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/git-ogawa/setup_kube_cluster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fsetup_kube_cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fsetup_kube_cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fsetup_kube_cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fsetup_kube_cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-ogawa","download_url":"https://codeload.github.com/git-ogawa/setup_kube_cluster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fsetup_kube_cluster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34412786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ansible","ansible-playbook","ec2-instance","kubernetes-cluster"],"created_at":"2024-11-10T20:10:56.281Z","updated_at":"2026-06-16T15:31:42.587Z","avatar_url":"https://github.com/git-ogawa.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\u003c!-- @import \"[TOC]\" {cmd=\"toc\" depthFrom=1 depthTo=6 orderedList=false} --\u003e\n\n\u003c!-- code_chunk_output --\u003e\n\n- [setup kube-cluster](#setup-kube-cluster)\n- [Requirements](#requirements)\n- [Quickstart](#quickstart)\n- [Configuration](#configuration)\n  - [Ingress controller](#ingress-controller)\n  - [HA cluster](#ha-cluster)\n  - [Tools](#tools)\n    - [Alias](#alias)\n    - [Completion](#completion)\n- [Task runner](#task-runner)\n  - [command list](#command-list)\n  - [Logging](#logging)\n- [Details](#details)\n- [Troubleshooting](#troubleshooting)\n  - [Setup fails due to rate limit for github REST API](#setup-fails-due-to-rate-limit-for-github-rest-api)\n- [Support distributions](#support-distributions)\n\n\u003c!-- /code_chunk_output --\u003e\n\n\n\n# setup kube-cluster\n\nThis repository is for setting up a kubernetes cluster for development on cloud instances (AWS EC2) by `Ansible`. It is useful to build a cluster in the following environments.\n\n- Cluster on EC2 instances instead of cloud-managed service (EKS).\n- Baremetal cluster on your local environment such as raspberry pi.\n\n\nA node that runs Ansible (referred to as executor here) creates kubernetes cluster using kubeadm. The cluster consists of the following nodes.\n\n- One control node including control plane components\n- Multiple worker nodes (optional)\n\n![Cannot load image](docs/images/component.png)\n\n\n# Requirements\nAn executor requires ansible module.\n\n- ansible \u003e= 2.10.0\n- ansible-playbook \u003e= 2.10.0\n\nThe executor also requires [kubernetes module](https://docs.ansible.com/ansible/latest/collections/kubernetes/core/k8s_module.html) to deploy manifests to cluster using ansible module. Install the kubernetes collection using `ansible-galaxy`.\n\n```\n\nansible-galaxy collection install kubernetes.core\n```\n\n\n\nThe control node and workers need to meet [kubernetes hardware requirements](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) and to install python3.\n\n\n# Quickstart\nClone the repository.\n\n```\ngit clone https://github.com/git-ogawa/setup_kube_cluster\ncd setup_kube_cluster\n```\n\nThe configuration for k8s cluster is written in `inventory.yml` (this is [inventory in Ansible](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html)).\n\nTo create for control plane set the following variables.\n\n- IPv4 address to the node for control plane.\n- SSH username, port and ssh key of your node under `control-node-1` in `inventory.yml`. control-node-1 is the hostname in ansible, which can be changed as you like.\n\n```yml\n# inventory.yml\nall:\n  ...\n  children:\n    control_plane:\n      hosts:\n        control-node-1:\n          ansible_host: 10.10.10.10  # IPv4 address\n          ansible_user: ubuntu  # SSH Username\n          ansible_ssh_port: 22  # SSH port\n          ansible_ssh_private_key_file: ~/.ssh/id_rsa  # Path to ssh key on executor\n```\n\nTo add worker nodes to cluster, set variables per worker node in the same way under `worker` field. The following are the example to add two host `worker-1` and `worker-2` to the k8s cluster as worker nodes.\n\n``` yaml\nall:\n  ...\n  children:\n    worker:\n      vars:\n        # Common variables for all workers can be set here.\n        ansible_ssh_port: 22\n        ansible_ssh_private_key_file: ~/.ssh/id_rsa\n        ansible_user: ubuntu\n      hosts:\n        worker-1:\n          ansible_host: 10.0.0.13\n        worker-2:\n          ansible_host: 10.0.0.14\n          ansible_user: ubuntu\n```\n\n\nThe `flannel` is used for CNI by default. When you want to use other CNI, set the CNI name to `cni_type` and cidr `network_cidr`. The supported cni are the followings.\n\n- calico\n- flannel\n\n\n``` yaml\nall:\n  vars:\n    cni_type: calico\n    network_cidr: \"10.244.0.0/16\"\n```\n\n\nTo create a new cluster, run the following command to create the cluster.\n\n```\n$ ansible-playbook setup.yml\n```\n\nThe setup playbook installs the necessary CLI, creates the cluster, and deploys the following components. You can manage whether each component is installed during the installation process by editing the inventory file. See [setup_cluster.md](docs/setup_cluster.md) for details.\n\n\n| Component                | Category                                | Installed by default |\n| ------------------------ | --------------------------------------- | -------------------- |\n| Nginx ingress controller | Ingress controller                      | yes                  |\n| Traefik                  | Ingress controller and proxy            | no                   |\n| OpenEBS                  | Storage                                 | no                   |\n| Longhorn                 | Storage                                 | no                   |\n| Kubevious                | Dashboard                               | no                   |\n| Octant                   | Dashboard                               | no                   |\n| Tekton                   | CI/CD platform                          | no                   |\n| Argocd                   | CD tool                                 | no                   |\n| Harbor                   | Image registry                          | no                   |\n| Gitea                    | Git server                              | no                   |\n| Kube-prometheus-stack    | Monitoring                              | no                   |\n| Openfaas                 | Serverless framework                    | no                   |\n| Cert manager             | Certificates management                 | no                   |\n| Jaeger                   | Distributed tracing system              | no                   |\n| Linkerd                  | Service mesh                            | no                   |\n| Velero                   | Backup and restore management           | no                   |\n| Awx                      | Web-based platform for Ansible          | no                   |\n| Stackstorm               | Platform for integration and automation | no                   |\n\n# Configuration\n\n## Ingress controller\n\nYou can deploy nginx or traefik as ingress controller. Set `ingress_controller.type` which to use in `inventory.yml`.\n\n```yml\nall:\n  vars:\n    # nginx or traefik\n    ingress_controller:\n      type: nginx\n```\n\n- [nginx ingress controller](https://github.com/kubernetes/ingress-nginx)\n- [traefik](https://github.com/traefik/traefik-helm-chart)\n\n\n## HA cluster\n\nThe project can create HA (High Availability) cluster consisting of stacked control plane nodes with kubeadm. The nodes that meet the following requirements are required to create the HA cluster.\n\n- Two or more node that meet requirements (see [Creating Highly Available Clusters with kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/#before-you-begin) ) are required as control plane nodes.\n- One or more load balancer that routing to nodes on control plane.\n\n\nTo create HA cluster, set `ha_cluster.enabled: true` in inventory file.\n\n``` yml\nall:\n  vars:\n    ...\n    ha_cluster:\n      enabled: true\n```\n\nSet host definitions used as nodes on control plane, worker nodes and load balancer.\n\n- Set name of hosts (e.g. kube-master1 below) to match the hostname on the node.\n- When the ip address used for communication between nodes is different from the one used by the node running the playbook for ssh (such as public ip or floating ip), set the former value `internal_ipv4`. Otherwise, set the same value for `ansible_host` and `internal_ipv4` or not set internal_ipv4.\n\n\n```yml\n# inventory\nall:\n  ...\n  children:\n    cluster:\n      vars:\n        # Common variables for all nodes can be set here.\n        ansible_ssh_port: 22\n        ansible_ssh_private_key_file: ~/.ssh/id_rsa\n        ansible_user: ubuntu\n      children:\n        control_plane:\n        worker:\n    control_plane:\n      # Define Two or more hosts to be used as control plane.\n      hosts:\n        kube-master1:\n          ansible_host: 10.10.10.11\n          internal_ipv4: 192.168.3.11\n        # If a node do not have external ip address such as floating IP,\n        # set the same ip address both ansible_host and internal_ipv4.\n        kube-master2:\n          ansible_host: 10.10.10.12\n          internal_ipv4: 192.168.3.12\n        # Or just not define internal_ipv4.\n        kube-master3:\n          ansible_host: 10.10.10.13\n    worker:\n      # Define zero or more hosts to be used as worker node.\n      hosts:\n        kube-worker1:\n          ansible_host: 10.10.10.14\n          internal_ipv4: 192.168.3.14\n    load_balancer:\n      # Define One or more hosts to be used as load balancer.\n      hosts:\n        # If set DNS name as control plane endpoint, add dns_name field.\n        load-balancer1:\n          ansible_host: 10.10.10.20\n          internal_ipv4: 192.168.3.20\n          dns_name: my-load-balancer.domain.com\n```\n\n\nThen run `setup.yml`.\n\n```\n$ ansible-playbook setup.yml\n```\n\nIf successfully finished, multiple control plane nodes are created as shown below.\n```\n$ kubectl get node\nNAME           STATUS   ROLES           AGE   VERSION\nkube-master1   Ready    control-plane   93m   v1.26.0\nkube-master2   Ready    control-plane   83m   v1.26.0\nkube-master3   Ready    control-plane   81m   v1.26.0\nkube-worker1   Ready    \u003cnone\u003e          41m   v1.26.0\n```\n\n\n## Tools\n\nUseful CLI tools and plugins to make it more comfortable to debug and develop for k8s can be installed during the setup. To enable this, set `k8s_plugins.enabled: true` in inventory.yml.\n```yml\nall:\n  vars:\n    k8s_plugins:\n      enabled: true\n```\n\nRunning the playbook will run sub-play to install the tools during k8s setup.\n```\nansible-playbook setup.yml -t k8s_plugins\n```\n\nOr run with `-t k8s_plugins` only to install the tools.\n```\nansible-playbook setup.yml -t k8s_plugins\n```\n\n\nThe following tools will be installed.\n\n- [popeye](https://github.com/derailed/popeye)\n- [kubectx](https://github.com/ahmetb/kubectx)\n- [fzf](https://github.com/junegunn/fzf)\n- [kubecolor](https://github.com/kubecolor/kubecolor)\n- [stern](https://github.com/stern/stern)\n\nNote: Only zsh is supported.\n\n### Alias\n\nAliases will be set to some commands to make input commands easier. The settings are stored in `~/.k8s_alias`.\n\n```sh\nalias k=\"kubecolor\"\nalias stern=\"kubectl-stern\"\n# -- BEGIN inserted by kubectx ansible task --\nalias ns=\"kubens\"\nalias ctx=\"kubectx\"\n# -- END inserted by kubectx ansible task --\n```\n\n### Completion\n\nCompletion will be set to some commands to make input commands easier. The settings are stored in `~/.k8s_plugin_setting`.\n\n```sh\n# -- BEGIN inserted by kubecolor ansible task --\nsource \u003c(kubectl completion zsh)\ncompdef kubecolor=kubectl\n# -- END inserted by kubecolor ansible task --\n# -- BEGIN inserted by popeye ansible task --\nsource \u003c(popeye completion zsh)\n# -- END inserted by popeye ansible task --\n# -- BEGIN inserted by stern ansible task --\nsource \u003c(stern --completion=zsh)\n# -- END inserted by stern ansible task --\n# -- BEGIN inserted by kubectx ansible task --\nfpath=($ZSH/custom/completions $fpath)\nautoload -U compinit \u0026\u0026 compinit\n# -- END inserted by kubectx ansible task --\n```\n\n\n# Task runner\n\n[Task runner](https://github.com/go-task/task) is supported for running commands more easier. Make sure that [task install](https://taskfile.dev/installation/) to use the feature.\n\n\n## command list\n\nRun setup (equivalent to  `ansible-playbook setup.yml`)\n\n```\ntask\n```\n\nRun the specific role or task with tags (equivalent to  `ansible-playbook setup.yml -t [tags]`)\n\n```\ntask tags -- [tags]\n```\n\nWhen specifying more than one tag, separate them with comma.\n\n```\ntask tags -- tag1,tag2,tag3\n```\n\n\nCleanup the current cluster (equivalent to  `ansible-playbook playbook/cleanup_cluster.yml`)\n\n```\ntask cleanup\n```\n\nCreate cluster (just create cluster by kubeadm and install ingress controller, not install additional component.)\n```\ntask cluster\n```\n\nRecreate cluster (run `task cleanup` and `task cluster`)\n\n```\ntask recreate\n```\n\n## Logging\n\nBy default, the output from the playbook is displayed in stdout and stderr.\nYou can use the command \"set logfile=[filename]\" on running tasks to log the outputs.\nFor example, the command below will run setup.yml and record the playbooks result in the `ansible.log`.\n\n```\ntask logfile=ansible.log\n```\n\n\n# Details\nSee [setup_cluster.md](docs/setup_cluster.md)\n\n# Troubleshooting\n\n## Setup fails due to rate limit for github REST API\n\nThe some tasks run github REST API during setup in order to install some binaries and packages.\nSince there is [rate limit for REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28), the setup may fail due to rate limit when running the setup several times in a short period of time.\n\nTo avoid this issue, set `github_api_token_enabled: true` and value of the github token for REST API in inventory. This raises the rate limit since run the API as authenticated user.\n```yml\n  vars:\n    github_api_token_enabled: true\n    github_api_token: \u003cyour_token\u003e\n```\n\n\n# Support distributions\n\nThe playbooks are tested against on the following distributions.\n\n- Ubuntu\n    - 23.04\n    - 24.04\n    - 24.10\n    - 25.04\n- Rockylinux\n    - 9.2\n    - 9.4\n    - 9.5\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fsetup_kube_cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-ogawa%2Fsetup_kube_cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fsetup_kube_cluster/lists"}