{"id":16070295,"url":"https://github.com/piontec/free-oci-kubernetes","last_synced_at":"2025-10-22T15:31:48.640Z","repository":{"id":182248858,"uuid":"668186964","full_name":"piontec/free-oci-kubernetes","owner":"piontec","description":"A TerraForm and Flux 2.0 template to easily bootstrap a GitOps managed kubernetes cluster using OCI's free tier","archived":false,"fork":false,"pushed_at":"2024-11-25T15:11:51.000Z","size":266,"stargazers_count":25,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-25T16:25:09.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/piontec.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-19T08:19:08.000Z","updated_at":"2024-11-25T15:12:25.000Z","dependencies_parsed_at":"2024-01-25T16:30:55.400Z","dependency_job_id":"9e21f934-f409-460d-b58e-807faeedfb4b","html_url":"https://github.com/piontec/free-oci-kubernetes","commit_stats":null,"previous_names":["piontec/free-oci-kubernetes"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piontec%2Ffree-oci-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piontec%2Ffree-oci-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piontec%2Ffree-oci-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piontec%2Ffree-oci-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piontec","download_url":"https://codeload.github.com/piontec/free-oci-kubernetes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237713376,"owners_count":19354728,"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":[],"created_at":"2024-10-09T07:01:54.224Z","updated_at":"2025-10-22T15:31:48.634Z","avatar_url":"https://github.com/piontec.png","language":"HCL","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# Free OCI Kubernetes Cluster with GitOps\n\nBy applying this repository you will get a completely free (still, as of Q1 2025, using the free tier of Oracle Cloud) Kubernetes cluster that has important applications already\npre-installed and is fully GitOps drive using Flux CD.\n\nIn more details, by following this guide you'll get:\n\n- a completely free Kubernetes cluster, with 2 nodes, each wit 4 core ARM CPU, 12 GBs of RAM and 50 GB of storage (using the Oracle Cloud Infrastructure)\n- a fully GitOps driven Kubernetes cluster using Flux CD, including\n  - nginx-ingress-controller\n  - cert-manager\n  - monitoring setup, including Prometheus, Loki and Grafana\n  - personal notifications about the alerts and health of your cluster\n  - optional extra features, like a wireguard VPN server exposing your cluster deployments\n\n## Index\n\n- How to create your own cluster - this document\n- [Design considerations](design.md)\n- [Extras](extras.md) - optional extra modules\n\n## Getting started\n\n### Intro\n\nBefore we can start creating the cluster, we need to first bootstrap our cloud infrastructure, our security keys and other secrets\nthat we need to run all the applications.\n\n### 1. Tools you need to have installed\n\nBefore we start, make sure that you have installed (tested on Linux, should work on other OSes as well):\n\n- tofu - this is a fork of the well-known TerraForm project, we'll use it to bootstrap our cloud infrastructure\n- flux - the CLI for controlling flux deployment\n- sops - a secret encryption tool that we use to securely keep all secrets in the repository\n- gpg - encryption tool that we will use as a backend for `sops`\n- [oci oracle cloud cli](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) - a CLI tool to control infrastructure in the OCI\n\n### 2. Preparing your repository\n\nYour cluster will be driven form your own repository, that has to be a copy of this one. Create a fork of this repository\n(I recommend keeping it private) and check it out on your local drive. If not stated otherwise, all the commands and files in\nthis guide will assume we're in the root directory of your repository.\n\n### 3. Bootstrapping the cloud infrastructure\n\nBefore you start creating any infrastructure, you need to register a new account with Oracle Cloud. You need to have a valid credit\ncard to register, even though the whole setup here is tailored to not use any paid resources and max out the free tier the OCI offers.\n\nGo to \u003chttps://signup.oraclecloud.com/\u003e and create a new account. Some services, especially related to Kubernetes, are not included\nin the free tier, but are still available to be used for free. Do be able to use them, you have to upgrade your billing tier. Go to\nyour [billing settings](https://cloud.oracle.com/invoices-and-orders/upgrade-and-payment), then click on \"Add card\" and \"upgrade your account\".\nOnce again, all the resource we use are available (at the time of writing and ofr the last at least a year) for free. Now you have to wait until\nyour billing tier change is processed.\n\n#### 3.1. Creating the infrastructure\n\nIn your terminal, run:\n\n```sh\noci setup config\n```\n\nThis will guide you through the process of setting up CLI access to OCI infrastructure. Read the documents printed by the `setup` command\nto learn where to find necessary input data.\n\nNext, go to the `tf/` directory in the repository and fill in information about your cloud account.\nCopy the template settings file `cp variables-private.tf.tpl variables-private.tf` and edit it:\n\n- insert your public SSH key as the `default` value for `ssh_public_key`\n- enter 'bastion allowed IPs', these are the IP addresses allowed to connect to the bastion host created for the cluster nodes\n- enter your default `compartment ID` - [here's how to find it](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/contactingsupport_topic-Locating_Oracle_Cloud_Infrastructure_IDs.htm)\n- enter your region and 2 Availability Domains within it\n- enter the `git_url` value that points to your repository\n- don't enter `git_token`, as we want this value to be secret (don't save it on your hard drive).\n\nNow, go to [github.com profile page](https://github.com/settings/profile) and generate a fine-grained private access token (PAT) with `repo` scope (Read and Write access to code). Here are [more details](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Copy the token and paste it into the `variables-private.tf` file as the `git_token` value.\n\nExport the PAT as environment variable\n\n```\n export GH_TOKEN=YOUR_PAT\n```\n\nIt's time to run `tofu` to bootstrap our cluster and obtain a `kube.config` file for it. Be patient, the first `apply` step can take pretty long (around half an hour):\n\n```sh\ntofu init\ntofu apply -var git_token=\"$GH_TOKEN\" -target local_file.kube_config\n```\n\nYour `kube.config` should be ready. You can test it with:\n\n```sh\nexport KUBECONFIG=$PWD/.kube.config\nkubectl version\nkubectl get nodes\n```\n\n### 4. Bootstrapping the GitOps setup\n\nWhile waiting for the infrastructure to be created, we can start filling in configuration necessary to set up Flux on our cluster.\n\n#### 4.1. Generating GPG key and configuring sops\n\nFirst, we have to configure an encryption tool, that will help us to store all the secrets in the repository in an encrypted form, but one\nthat is still automatically decrypted on the cluster.\n\nSwitch to the repo root folder.\n\nIf you don't have a ready GPG key, [here's a more detailed manual by GitHub about how to create one](https://docs.github.com/en/authentication/managing-commit-signature-verification/).\n\nIf you just want a kick-start, generate a new key with\n\n```txt\ngpg --full-generate-key\n```\n\nSave its key fingerprint that is printed out when the key is ready (and remove space between all the 4-characters blocks). We will use your GPG key\nwith `sops` tool, that will encrypt the secrets for use with Flux. Now, copy the `sops` config from template:\n\n```sh\ncp .sops.yaml.tpl .sops.yaml\n```\n\nthen edit the file and paste your key fingerprint.\n\nNext, save the private key to your cluster _without putting the key into the repo_:\n\n```txt\nkubectl create ns flux-system\ngpg --export-secret-keys --armor \"[KEY_FINGERPRINT]\" |\nkubectl create secret generic sops-gpg \\\n--namespace=flux-system \\\n--from-file=sops.asc=/dev/stdin\n```\n\n#### 4.2. Create a slack profile\n\nThis step is not really necessary, but it's very useful. Here we'll create a free slack profile, where we can receive notifications\nfrom Flux and from our monitoring setup. Slack notifications are pretty easy to set up and still can be completely free, but obviously feel\nfree to change this step later.\n\nFirst, [create a new slack profile](https://slack.com/get-started#/createnew). Then, create and save slack's webhook URL using [this instruction](https://api.slack.com/messaging/webhooks).\n\n#### 4.3. Preparing secrets\n\nIn the configuration repo, there are many secrets needed, usually passwords to different applications deployed. All files that need editing and filling in\nsome secrets have file names ending with `.tpl.enc`.\n\nFor each such file (see list below), you have to repeat the same procedure:\n\n- copy the file into the same name, but without the `.tpl.enc` suffix\n- fill in required secrets, remember to base64-encode them, for example `echo \"MY_GRAFANA_PASS\" | base64 -w 0`\n- **do not put the files into the repo yet, they are still plain-text**\n- encrypt the file with the command `sops -i -e flux/[FILE].yaml`\n- only now add your secrets are ready to be included in the GitOps repo\n\nYou need to process the following files with secrets:\n\n- ./flux-modules/flux-system-extra/github-api-token-secret.yaml.tpl.enc - paste your GitHub PAT again, so Flux can report back the status fo your commits\n- ./flux-modules/flux-system-extra/slack-flux-notification-url-secret.yaml.tpl.enc - enter here the Slack webhook you created earlier\n- ./flux-modules/monitoring/alertmanager-slack-api-secret.yaml.tpl.enc - again, include the Slack webhook URL\n- ./flux-modules/monitoring/prom-stack-grafana-pass-secret.yaml.tpl.enc - create a user password for the Grafana web UI\n\nAdditionally, you have to edit `postBuild` section of a few files to give information like your DNS name for hosting the cluster or admin's email address (required for\n`letsencrypt`). The files you need to edit are:\n\n- flux-modules/flux-system-extra/kustomization-flux-system-extra.yaml\n- flux-modules/kube-system-extra/kustomization-kube-system-extra.yaml\n- flux-modules/monitoring/kustomization-monitoring.yaml\n- flux-modules/extras/wireguard/kustomization-wireguard.yaml\n- flux-modules/extras/wireguard/kustomization-wireguard-pre.yaml\n\n#### 4.4. Bootstrap Flux\n\nStat by reading the [official documentation about bootstrapping Flux with Flux Operator](https://fluxcd.control-plane.io/operator/).\n\nRun `tofu` again, this time asking it to deploy the `flux-operator`\n\n```sh\n# run from the tf/ directory\ntofu apply -target helm_release.flux_operator -var git_token=\"$GH_TOKEN\"\n```\n\nRunning\n\n```sh\nkubectl -n flux-system get deploy\n```\n\nshould show you that the `flux-operator` deployment is up and running (`Ready: 1/1`).\n\nNow, we can create an actual Flux instance that will deploy all the applications we have in our GitOps repository. We can do full `tofu apply` now to make sure our full `tofu` config is deployed:\n\n```sh\ntofu apply -var git_token=\"$GH_TOKEN\"\n```\n\nMake sure that the `tofu` run is complete. Now, you can commit everything into your GitOps repository and push the changes, adding all the created terraform and \\*.yaml\nfiles to your repo. Check that all the files are in, especially `tofu` state files:\n\n- tf/terraform.tfstate\n- tf/terraform.tfstate.backup\n- tf/variables-private.tf\n- .terraform.lock.hcl\n\n```sh\ngit commit -am \"cluster bootstrap commit\"\ngit push\n```\n\nYour work should be done now! From now on, Flux takes over and adjusts your cluster configuration exactly as in your GitOps repository on GitHub.\n\nYou can check the status of the most important object by running the following commands:\n\n```sh\nkubectl get gitrepository -A\nkubectl get kustomization -A\n```\n\n### 5. Next steps\n\nYour cluster is ready. Now you can either forget about the repository you cloned (not recommended, but totally possible) and modify your repository however\nyou like. Or you can read on [keeping track and contributing back](#synchronizing-with-source-repository-and-providing-pull-requests).\n\n## Configuring the repository to run automatic Flux upgrade job\n\n## Synchronizing with source repository and providing pull requests\n\nAfter you bootstrap your own repository, you can forget about the one you forked it from. Still, it is beneficial to be able to get upstream changes,\nincluding new versions and new modules. Below is information useful in tracking and contributing to the upstream repository.\n\n### Fetching changes from the upstream repository\n\nIt is recommended to setup additional git source repository, then fetch and merge the changes with your selected branch:\n\n```sh\ngit remote add upstream https://github.com/piontec/free-oci-kubernetes.git  # run only once, if you don't have the upstream definition yet\ngit fetch upstream main\ngit merge upstream/main\n```\n\nNow you might need to resolve any potential merge conflicts. Once that's done, review the changes and you should be ready to push them to your branch for\nFlux to pick-up.\n\n### Preparing pull requests\n\nIt's best if you prepare a small and scoped PR. Please make also sure, that your code complies to `pre-commit` linting tests. To make it run automatically\nfor you, install [pre-commit](https://pre-commit.com/), then run:\n\n```txt\npre-commit install --install-hooks\n```\n\nFrom now on, all the commits will automatically validated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiontec%2Ffree-oci-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiontec%2Ffree-oci-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiontec%2Ffree-oci-kubernetes/lists"}