OpenShift Installer: A Go-Based Tool for Reproducible Cluster Lifecycle Management

What the OpenShift Installer Solves and Who It Is For

The OpenShift Installer addresses a specific pain: getting an OpenShift 4.x cluster running from zero without hand-assembling infrastructure. It is built for engineers who need a repeatable path from empty cloud account or bare metal rack to a working cluster. The README frames it as a binary that you build, then invoke with create cluster, and later destroy cluster. That is the whole lifecycle. The target user is someone comfortable with Go build steps and command-line prompts, likely a platform engineer or a developer who needs a test cluster quickly. It is not a GUI tool and not a managed service. The installer assumes you already have cloud credentials or bare metal access, and it handles the provisioning and configuration steps in between. The scope is narrow: create and destroy. That is the core value. For anyone who has struggled with multi-step installation guides, this tool collapses the process into two commands.

The Mechanism: Prompts, Config, and State Files

The installer works in two modes. In interactive mode, it shows a series of prompts for user-specific information, like cluster name and base domain, and uses reasonable defaults for everything else. In non-interactive mode, you bypass prompts by providing an install-config.yaml file, as documented in docs/user/overview.md. The README shows that after creation, the binary prints connection details and writes a log file named .openshift_install.log. The state is stored in an asset directory that includes auth/ and terraform.tfstate. That state directory is the key to destruction. The destroy cluster command reads that state to release associated resources. If you lose the state, cleanup becomes manual. The README explicitly warns that you almost certainly want to clean up installer state files after destroying, including auth/ and terraform.tfstate. The mechanism is stateful, and the state lives on disk. That is a design choice that makes the tool simple but also fragile if you misplace the directory.

Getting It Running: Build and Invoke

To use the installer, you first install all build dependencies, as listed in docs/dev/dependencies.md. Then clone the repository and run hack/build.sh. That script creates bin/openshift-install. From there, the commands are direct: bin/openshift-install create cluster starts the process, and openshift-install destroy cluster tears it down. The README gives an example of successful output, which includes a wait for the openshift-console route and then prints the kubeconfig path and console URL. The critical advice, repeated in the README, is to always pass the --dir argument to both create and destroy. The --dir argument specifies the asset directory, which holds the state files. Without it, the installer uses a default directory, which can lead to confusion when you have multiple clusters. The README also suggests that if you want to reinstall from scratch, you should rm -rf the asset directory beforehand. That is a concrete, practical command that shows how the tool expects you to manage state.

Supported Platforms: Broad but Not Universal

The README lists ten supported platforms: AWS, Azure, Bare Metal, GCP, IBM Cloud, Nutanix, OpenStack, Power, Power VS, vSphere, and z/VM. Each has a link to platform-specific documentation under docs/user/. This breadth is a strength, but it also means the installer is not a single universal tool. The behaviour can vary by platform, and the documentation for each platform is separate. For example, bare metal installation likely involves different networking and provisioning steps than a cloud deployment. The README does not detail those differences, so you must consult the platform docs. That is a limitation: the README gives a uniform interface, but the underlying implementation is not uniform. If your platform is not on the list, you cannot use this installer. That is a hard boundary. For a team running on an unsupported cloud, this tool is the wrong choice from the start.

The --dir Argument: A Simple Rule with Real Consequences

The README makes a pointed recommendation: the best thing to do is always pass the --dir argument to create and destroy. This is not a minor style note. The --dir argument determines where the installer stores its state, including auth credentials and the Terraform state file. If you omit it, the installer uses a default directory, and you risk mixing state from different clusters or losing track of which directory belongs to which cluster. The consequence is that destroy cluster may not find the right state, leaving resources running in the cloud and costing you money. The README's advice is to pass --dir every time, and to rm -rf the asset directory before reinstalling. That is a concrete operational discipline. The tool does not enforce it, so you must remember. This is a genuine failure mode: the installer will happily create a cluster without --dir, and you might not notice until cleanup fails. The README's phrasing, almost certainly, signals that this is a known pitfall.

Limitations: State Dependency and Non-Interactive Setup

The biggest limitation is the reliance on local state files. If you lose the asset directory, you cannot destroy the cluster with the installer. You would have to clean up resources manually, which defeats the purpose. The README does not mention any remote state option. That is a design trade-off: simplicity over resilience. Another limitation is the interactive prompt flow. The README says prompts can be bypassed with install-config.yaml, but that requires reading docs/user/overview.md. In a CI/CD pipeline, you need that non-interactive mode, and the README does not give an example of the YAML structure. You must dig into the docs. Also, the installer only handles create and destroy. It does not update or upgrade clusters. For upgrades, you would need a separate tool like the OpenShift Cluster Manager or oc adm. So the installer is not a full lifecycle tool. It is the front door and the back door, but not the house maintenance.

Alternative Approaches: Comparison to Cluster API or Manual Terraform

A real alternative is the Cluster API project, which takes a declarative, Kubernetes-native approach to cluster lifecycle. Instead of a single binary that you run, Cluster API uses custom resources and controllers to manage clusters, and it supports operations like scaling and upgrading. The difference in approach is fundamental: the OpenShift Installer is imperative and stateful on disk, while Cluster API is declarative and stores state in a Kubernetes cluster. Another alternative is to use Terraform directly with the OpenShift provider or community modules. That gives you more control over infrastructure but requires you to write and maintain the Terraform code yourself. The OpenShift Installer hides that complexity, but it also hides the details. If you need to customize the infrastructure beyond what the installer supports, you would have to fork or modify the installer, which is not trivial. For teams already using Kubernetes as a control plane, Cluster API offers more flexibility, but it has a steeper learning curve. The OpenShift Installer is the quickest path to a default cluster, but it is also the least flexible.

Maintenance and Upgrade Costs Plus Licence Notes

The repository is written in Go and licensed under Apache-2.0, which permits use, modification, and distribution with conditions. The README does not describe a formal upgrade path for the installer itself. You build from source, so you control the version by checking out a specific release tag like v0.90.16 or v0.91.0. The release naming suggests a branch-per-OpenShift-version pattern, such as release-4.16 and release-4.17. That means you should pick a release that matches your OpenShift version. The maintenance cost is that you must rebuild the binary when you want to update. There is no package manager installation shown. The build script, hack/build.sh, compiles the binary, and you need to manage the Go dependencies yourself. The README does not mention any automatic update mechanism. So the upgrade cost is manual: pull new code, rebuild, and test. The licence is permissive, but the real cost is the time to rebuild and the risk of version mismatch. The Apache-2.0 licence means you can integrate the installer into your own tooling, but you must retain the licence notices.

Editorial conclusion

Adopt OpenShift Installer if you need a straightforward, scriptable way to stand up OpenShift 4.x clusters on AWS, Azure, GCP, bare metal, or other listed platforms, and you value a single binary that handles both creation and destruction. Avoid it if you require fine-grained control over cluster lifecycle beyond create and destroy, or if you need to manage clusters on platforms not listed in the README. Before adopting, verify that your target platform is supported, review the docs/user/overview.md for non-interactive configuration, and test the destroy command with --dir in a non-production environment to confirm it cleans up all resources as expected. The installer is a pragmatic tool, but it is not a full cluster management platform.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes