# openshift/installer: Building the openshift-install Binary and Creating a Cluster

> The openshift/installer repository builds the openshift-install binary that provisions OpenShift 4.x clusters across eleven supported platforms. It is a build-from-source tool for platform engineers, and its asset directory behaviour is the part most people get wrong.

**openshift/installer** — Install an OpenShift 4.x cluster. The best thing to do is always pass the dir argument to create and destroy.

- Repository: https://github.com/openshift/installer
- Website: https://try.openshift.com
- Stars: 1,558 · Forks: 1,518
- Language: Go
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/openshift-installer

## What openshift/installer Actually Provisions

OpenShift 4.x clusters are not assembled by hand. The openshift/installer repository exists to produce one binary, openshift-install, and that binary drives the whole provisioning sequence for a cluster on a supported platform. The README lists eleven of them: AWS, Azure, Bare Metal, GCP, IBM Cloud, Nutanix, OpenStack, Power, Power VS, vSphere and z/VM. Each has a directory under docs/user/ and a link to the corresponding page in the official OpenShift container platform installation documentation.

The audience is narrow and specific. This is for the person who owns the infrastructure account, holds the platform credentials, and is expected to hand back a working cluster with a kubeconfig. It is not a developer-facing tool for spinning up a throwaway environment. The installer makes real decisions: it creates cloud resources, configures networking and DNS, and bootstraps the control plane. The README's own framing is that the binary prompts for user-specific information and uses reasonable defaults for everything else, which tells you the intended path is interactive first and scripted second.

That split matters. The interactive path is a convenience wrapper. The non-interactive path, described in docs/user/overview.md under multiple invocations, is the one production teams actually depend on, because it lets the same install-config.yaml be replayed. If you only ever run the prompts, you have not yet used the part of the tool that makes it repeatable.

## How the Installer Turns a Config into a Running Cluster

The repository layout shows the shape of the machine. There is cmd/ for the binary entry points, pkg/ and internal/ for the implementation, data/ for the assets the installer renders, and upi/ alongside cluster-api/. The go.mod file is the clearest signal of what the tool actually talks to: it depends directly on cloud SDKs, including the Azure resource manager modules for compute, network, DNS, key vault and managed identity, the Google Cloud KMS, monitoring and storage clients, and IBM Cloud clients for power, object storage and key management. There is no abstraction layer hiding the providers; each platform has its own client code and its own credential handling.

The flow the README describes is: gather input, either through prompts or through an install-config.yaml, then create the cluster. During that run the installer writes a set of state files into an asset directory. The README names auth/ and terraform.tfstate among them, and the example completion output shows a kubeconfig path at auth/kubeconfig, a console URL of the form console-openshift-console.apps.${CLUSTER_NAME}.${BASE_DOMAIN}:6443, and a generated kubeadmin password. The presence of terraform.tfstate is the important architectural detail: the installer's state is not purely in the cluster, it is on the machine that ran the command.

That single fact explains most of the operational advice in the README. Because state lives in a directory, the directory is the unit of identity. Move it, lose it, or let two runs share it, and destroy stops being a reliable inverse of create. The README states plainly that you almost certainly also want to clean up the installer state files, and that the best thing to do is always pass the --dir argument to create and destroy.

## Installing openshift-install and Creating Your First Cluster

There is no package manager step in the README. The documented route is a source build. First install the build dependencies listed in docs/dev/dependencies.md, then clone the repository and run the build script:

```bash
hack/build.sh
```

The script produces the binary at bin/openshift-install. Nothing is installed system-wide by this step; the binary lives inside the checkout, so you invoke it by path.

With the binary built, the README's quick start is a single command:

```bash
bin/openshift-install create cluster
```

The installer then presents a series of prompts for user-specific information and fills in defaults for the rest. Answer them and the run proceeds. For a non-interactive context the README points at docs/user/overview.md, which documents supplying an install-config.yaml so the prompts can be bypassed. That file is the input you keep in version control; the prompts are not.

When the run finishes, the binary prints connection details. The README's example output shows the form to expect:

```bash
INFO To access the cluster as the system:admin user when using 'oc', run
    export KUBECONFIG=/path/to/installer/auth/kubeconfig
INFO Access the OpenShift web-console here: https://console-openshift-console.apps.${CLUSTER_NAME}.${BASE_DOMAIN}:6443
```

The same details are written to .openshift_install.log, so a lost terminal does not lose the kubeconfig path. To tear the cluster down, the README gives:

```bash
openshift-install destroy cluster
```

Run create and destroy with an explicit --dir. The README's closing advice is that if you want to reinstall from scratch you should rm -rf the asset directory beforehand, which only works if you know exactly which directory that is.

## The --dir Argument and the State Directory Trap

The README repeats one instruction more than any other: pass --dir to create and destroy. It is worth taking literally. Without it, the installer picks a directory for you, and the destroy command later has to find the same state. If you ran create from one working directory and destroy from another, or if a CI job used an ephemeral workspace, the terraform.tfstate and the auth/ directory may not be where destroy looks.

The failure mode is not a crash. It is a destroy that cannot map back to the resources it created, leaving cloud objects running and billing. The README anticipates this and says you almost certainly also want to clean up the installer state files, listing auth/ and terraform.tfstate explicitly. That sentence is doing a lot of work: it admits that the tool does not fully own its own cleanup.

A second trap follows from the first. The README says that to reinstall from scratch you should rm -rf the asset directory beforehand. If you keep one directory and reuse it, stale state from a previous cluster can be picked up. If you delete it before you have destroyed the old cluster, you lose the ability to destroy it cleanly. The safe pattern is one directory per cluster, named after the cluster, created before the first run and removed only after destroy returns. This is not documented as a rule; it is the consequence of the state model the README describes.

## Where openshift-install Is the Wrong Tool

The README's platform list is also its boundary. If your target is not AWS, Azure, Bare Metal, GCP, IBM Cloud, Nutanix, OpenStack, Power, Power VS, vSphere or z/VM, the repository does not claim to support you. There is no generic provider plugin interface described in the README, and the go.mod dependency list shows per-cloud SDK imports rather than a single neutral API, so adding a new platform is a code contribution, not a configuration change.

The second boundary is the build requirement. The README's quick start begins with installing build dependencies and running hack/build.sh, and go.mod pins a Go toolchain version. Teams that expect to download a signed binary and run it will not find that path in this material. That is a real cost for air-gapped or tightly controlled build environments, where bringing in a Go toolchain and the vendored dependency tree is a separate approval exercise.

The third boundary is scope. This installer creates clusters. It does not manage their lifecycle afterwards, does not upgrade them, and does not reconcile drift. The README's cleanup section is about releasing resources, not about operating them. If what you need is day-two cluster management, you are looking at the wrong repository, and the README does not pretend otherwise.

## openshift-install Versus a Kubernetes Distribution Installer

The natural comparison is with the installers that ship alongside upstream Kubernetes distributions, such as kubeadm. The difference is in what each one assumes it owns.

kubeadm assumes you have already built the machines, installed a container runtime, configured the network and set up the load balancer. It joins nodes and starts the control plane. It is a component, and it leaves the surrounding infrastructure to you or to another tool.

openshift-install assumes the opposite. The README's platform list and the cloud SDK dependencies in go.mod show that it provisions the infrastructure itself: compute, networking, DNS, storage and identity are all in scope. The output is not a set of nodes waiting to be joined but a cluster with a console route, a kubeadmin credential and a kubeconfig, printed at the end of the run.

That difference determines the failure modes. With kubeadm, a bad network setup is your bug. With openshift-install, the installer is the thing creating the network, so a failure during creation leaves partially created cloud resources that you have to find and remove. It also determines reversibility: kubeadm leaves no state file that a later command needs, while this installer writes terraform.tfstate and auth/ and depends on them for destroy. Neither approach is better in the abstract. They sit at different points on the line between a component and a provisioner.

## Maintenance, Licensing and What an Upgrade Costs You

The repository is not archived, and the last push to main was on 2024-09-26. The most recent releases listed are v0.90.16 for the release-4.16 branch, v0.90.17 for release-4.17, and v0.91.0, all dated 2024-09-26. The version scheme is worth reading carefully: the release tags track OpenShift release branches rather than a single linear product version, so a v0.90.x tag is not simply older than a v0.91.x tag in the way the numbers suggest. If you need the installer for a particular OpenShift minor release, you want the tag matching that branch, not the numerically highest one.

Upgrade cost is dominated by the build. Because there is no documented binary download in this material, moving to a newer installer means checking out a different tag and running hack/build.sh again, with whatever dependency changes that tag brings. The go.mod file is large and includes beta-versioned modules, so a jump between branches can pull in changed cloud SDK versions. Budget for that as a rebuild-and-retest cycle, not a drop-in replacement.

The licence is Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. Apache-2.0 includes a patent grant and requires that the NOTICE contents be preserved in redistributions, which matters if you plan to ship a modified installer internally. The repository also contains a DCO file, indicating contributors sign off on their commits. None of this is legal advice; if you intend to redistribute a modified binary, have your own counsel read the LICENSE and NOTICE rather than relying on a summary.

## Conclusion

Adopt openshift/installer if you provision OpenShift 4.x clusters on one of the eleven platforms it lists and you are willing to build the binary from the repository with hack/build.sh. Do not adopt it if you want a managed control plane, a single-node developer cluster on your laptop, or a tool with a stable released binary you can download without a Go toolchain; the README points at build dependencies and a source build instead. Before you start, verify that your target platform appears in the supported list, that your machine satisfies docs/dev/dependencies.md, and that you have decided on a fixed --dir path, because the repository states that the best practice is to always pass --dir to create and destroy. The last push to main was on 2024-09-26.

## FAQ

### How do I build the openshift-install binary from the openshift/installer repository?

Install the build dependencies listed in docs/dev/dependencies.md, clone the repository, and run hack/build.sh. The script creates the binary at bin/openshift-install.

### Which platforms does openshift/installer support for creating a cluster?

The README lists AWS, Azure, Bare Metal, GCP, IBM Cloud, Nutanix, OpenStack, Power, Power VS, vSphere and z/VM. Each has a directory under docs/user/ and a link to the corresponding official installation page.

### Why does the openshift/installer README say to always pass the --dir argument?

The installer writes state files into an asset directory, including auth/ and terraform.tfstate, and destroy depends on finding that same state. The README states that the best thing to do is always pass the --dir argument to create and destroy.

### How do I remove an OpenShift cluster created with openshift-install?

Run openshift-install destroy cluster. The README notes that you almost certainly also want to clean up the installer state files, including auth/ and terraform.tfstate, and that you should rm -rf the asset directory before reinstalling from scratch.

### Can openshift-install run without interactive prompts?

Yes. The README states that in non-interactive contexts the prompts can be bypassed by providing an install-config.yaml, documented in docs/user/overview.md under multiple invocations.

### What licence does openshift/installer use?

The repository is licensed under Apache-2.0 and includes both a LICENSE and a NOTICE file, along with a DCO file for contributor sign-off.

## Sources

- [Official documentation](https://try.openshift.com)
- [Official README](https://github.com/openshift/installer#readme)
- [Project repository](https://github.com/openshift/installer)
- [Release notes](https://github.com/openshift/installer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openshift-installer