oke-free: standing up a Kubernetes cluster on Oracle's always free tier with OpenTofu

The account is free, but the cluster probably is not

oke-free is described in Portuguese as an easy way to guarantee your own Kubernetes cluster for free and forever. The project was written for the MesDoKubernetes community event, and the readme is titled around creating a Kubernetes cluster in OCI using OpenTofu.

The headline claim needs the caveat the readme itself puts first. Because of the limitations of the free account, you will probably need to upgrade to a Pay As You Go account to create the cluster using the free VM.Standard.A1.Flex instances. You will not be charged for the use of free resources even after the upgrade.

That is a different proposition from a free account. A pay as you go account is a card on file with a billing relationship, and the reason the configuration exists at all is that the always free tier in OCI includes ARM Ampere A1 shapes, which is what OKE needs to run a control plane without a fee.

The readme names the second thing to do before you start: create a Budget alert in your account so you are not charged by accident. The link goes to the OCI budgets page. This is the correct advice and it is the advice most people skip, because a budget alert is easy to dismiss as an upsell and the billing shock, when it comes, is not.

The third point is a constraint rather than a warning. Do not change the shape of the instance used in the cluster, because the only free instance compatible with OKE is VM.Standard.A1.Flex. Every other shape in the OCI catalogue is billable, and OKE will happily accept one and start charging you.

For the intended user, a student or a developer who wants a cluster to try things on, this is a good trade. The tier provides a real managed control plane, a real node pool and real API, and the whole thing can be destroyed with a single destroy command at the end of the experiment.

Two directories of Terraform and a variable file you have to read

The repository is infrastructure as code with the modules split by resource area. The top level holds main.tf, variables.tf, outputs.tf and terrafile.tf, plus directories for cluster/, compartment/, kubeconfig/, loadbalancer/, network/ and manifests/, an examples/ directory with an ingress controller and service accounts example, and a main.sh script at the root.

That layout is the clearest statement of what the project does. The cluster module creates the OKE cluster and the node pool, the compartment module sets up the container compartment, the network module builds the VCN and subnets, the loadbalancer module handles the ingress, kubeconfig/ writes the kubeconfig, and manifests/ holds the Kubernetes manifests applied to the new cluster.

The variable file is where the decisions are, and the readme points at it explicitly for the Kubernetes version, telling you to use the same version that is written in variables.tf rather than a newer one. That is a sensible instruction, because a mismatched kubectl against an older API server produces errors that look like configuration problems.

The terrafile.tf file is an OpenTofu specific feature for splitting configuration across files, and it is the mechanism that lets the project keep the resource areas in separate directories while still presenting one root module.

The primary language is listed as HCL, and there are no GitHub releases, so the version history of the configuration lives in the commit log rather than in tags. The last push was on 2026-07-28, and the project was written in July 2026 based on the readme references and the event it accompanied.

Three tools to install before the Terraform runs

The readme covers three pieces of local tooling, each with a GNU/Linux route and a Windows route, and each step explains why it matters.

OpenTofu comes first, the open source fork of Terraform, installed with a shell script on Linux.

curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
chmod +x install-opentofu.sh
./install-opentofu.sh --install-method deb
rm install-opentofu.sh

The Windows route uses the PowerShell installer with the standalone install method.

The OCI CLI comes second, since it is what talks to the Oracle API. On Linux it is a shell install, and the readme walks through the interactive bits, including typing yes at the prompt to update the PATH variable so that .bashrc or .bash_profile is updated automatically, and needing to point at the right file yourself if you use a different shell such as zsh. Then restart the terminal session and check the result with oci -v.

On Windows the route is the MSI installer from the OCI CLI releases on GitHub.

kubectl is third, pinned to Kubernetes 1.28.2, downloaded as a linux amd64 binary and installed with sudo install -o root -g root -m 0755 into /usr/local/bin, with bash completion added to .bashrc. The readme notes that the version check prints a deprecation warning about version information being replaced by the output of kubectl version --short, and that you can ignore it because you are only checking which version you installed.

The Windows route downloads the windows amd64 kubectl.exe and asks you to add the bin directory to PATH, then validates with kubectl version --client --output=yaml.

Pinning kubectl to the same version as the cluster is the detail to carry away from all of this, because it is the one that bites when you skip it.

Authentication is a key file, a config file and an SSH key

The authentication section is the longest part of the readme, and it is the part where most people get stuck, so it is worth following closely.

You clone the repository, then in the OCI console you go to your profile, open the API Keys tab and click Add API Key. You select Generate API key pair, download the private key, and click Add. Then you move the key into the OCI CLI directory and rename it to oci_api_key.pem, which on Linux means creating ~/.oci and moving the file there.

The permissions on that key are then fixed with a dedicated command.

oci setup repair-file-permissions --file <caminho_da_chave_privada>

Next you copy the text shown on the API key creation page into the OCI CLI config file, substituting the private key path into the key_file field. The config is a small INI file with a DEFAULT section holding user, fingerprint, tenancy, region and key_file, and the readme shows both the Linux path at ~/.oci/config and the Windows path.

Then there is an SSH key, generated with ssh-keygen -t rsa -b 4096 into a ./ssh directory, and the readme notes that on Windows you should use Git Bash to run that command.

All of this feeds the env.sh file, which exports the Terraform variables.

export TF_VAR_tenancy_ocid=<your tenancy ocid>
export TF_VAR_user_ocid=<your user ocid>
export TF_VAR_fingerprint=<your fingerprint>
export TF_VAR_private_key_path=~/.oci/oci_api_key.pem
export TF_VAR_ssh_public_key=$(cat ssh/id_rsa.pub)
# Optional if you want to use a different profile name change the value below
export TF_VAR_oci_profile="DEFAULT"

The TF_VAR_ prefix is how Terraform picks up values from the environment without them appearing in the state file, which is the right way to pass an API key path. The Windows equivalent is an env.bat with set commands, executed to export the same variables.

Note that this puts credentials into a shell file on disk. The readme does not say to add env.sh to .gitignore, so a reader who commits the repository directory after running the setup is one git add away from publishing an API key path and a fingerprint. That is a small thing to check before your first commit.

Two commands, and an optional plan first

Creating the cluster is a two step process once the tools and credentials are in place. You install the modules with tofu init, and then you create the cluster with tofu apply.

tofu init

tofu apply

Before that, the readme suggests running a plan and saving it, which is good practice for infrastructure and costs nothing.

tofu plan -out=oci.tfplan
tofu apply -auto-approve "oci.tfplan"

The saved plan file has a side effect worth understanding. A plan captures the state of the world at the moment it was generated, and applying that saved plan rather than running a fresh apply is what makes the operation reproducible. It also means the plan becomes a record of exactly what was created, which is useful documentation for a cluster someone else will have to understand later.

The last step in the readme is to edit ~/.kube/config to add the API key authentication, following the example it shows.

So the sequence is: install three tools, create an API key, generate an SSH key, export the variables, initialise and apply, then wire up kubectl. It is a long list but every step is a standard piece of Oracle Cloud setup, and the Terraform part is the part that actually saves you time.

What the configuration gives you that the console does not is repeatability. Once it works, the same apply rebuilds the same cluster, and a destroy tears it down. For a workshop, a university lab or a conference talk where several people need the same environment, that difference is the whole value of the project.

Where oke-free is the wrong tool

Three limits, and the first one is financial rather than technical.

The free tier is not enough on its own. The readme says outright that you will probably need a pay as you go upgrade to use the free VM.Standard.A1.Flex instances, and that you will not be charged for the free resources even after upgrading. That is a reasonable arrangement, but it means someone needs a card on file and someone needs to watch the billing. A team with a hard no-cloud-spend policy cannot use this, and a team without credit card billing at all cannot use the OCI free tier in the first place.

The second limit is that the cluster is not portable and not production shaped. The shape is fixed to VM.Standard.A1.Flex and cannot be changed, the Kubernetes version comes from variables.tf rather than from whatever you want, and kubectl is pinned to 1.28.2 in the instructions. A cluster you build here is a cluster for experimenting with scheduling, autoscaling and ingress. It is not a cluster you would run a production service on, and the readme does not pretend otherwise.

The third limit is that the Terraform here is one configuration, not a maintained module. There are no GitHub releases, so there is no version history to pin, and a configuration that depends on a specific OCI free tier shape and a specific kubectl download URL ages quickly. The kubectl download in particular is a hardcoded 1.28.2 binary link, which is the kind of thing that rots silently as the Kubernetes project moves its download endpoints.

The alternatives differ in what they give you. A managed free tier from another cloud, such as the free control plane credit some providers offer, gives you a cluster without any infrastructure code and without the OCI billing relationship. A local cluster tool such as kind, minikube or k3d gives you a real API server and real nodes on your own machine for free, and for most learning goals that is a better fit than a cloud cluster. And writing the same Terraform yourself for a paid account gives you the same automation with a configuration you control, which is what you want if the goal is to learn the infrastructure rather than to get a cluster quickly.

Editorial conclusion

oke-free suits a developer or student who wants a real managed Kubernetes cluster to experiment with and has an Oracle Cloud account, since it turns a page of console clicking into a repeatable apply that can be torn down again. It does not suit anyone who cannot accept a paid cloud account, because the free tier alone is not enough and the documentation says you will probably need to upgrade to Pay As You Go, and it does not suit a production cluster because the instance shape is fixed to VM.Standard.A1.Flex. Before running it, create a Budget alert in the OCI console, because the free allowance ends silently and the documentation insists on that step, and read variables.tf, since the Kubernetes version and the shape are decided there.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Rapha-Borges/oke-free on GitHub
4. README