A Go-based installer for MicroShift clusters on AWS and GCP, modeled after openshift-installer.
Unlike wrapping Terraform HCL, this installer uses the cloud provider's native Go SDKs to provision resources directly:
- AWS: aws-sdk-go-v2 — EC2, VPC, Route53
- GCP: google-cloud-go / google-api-go-client — Compute Engine, Cloud DNS
The project provides two modes:
- CLI (original) — run
microshift-installerdirectly on your machine - Kubernetes Operator — manage clusters declaratively via CRDs inside a Kubernetes cluster
- Go 1.22+ (to build)
- A Red Hat subscription (for RHEL + MicroShift)
- An OpenShift pull secret (download from https://console.redhat.com/openshift/downloads#tool-pull-secret)
Cloud-specific:
| Cloud | Requirements |
|---|---|
| AWS | AWS credentials (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY or ~/.aws/credentials); Route53 public hosted zone |
| GCP | GCP project with Compute Engine, Cloud DNS, and Cloud NAT APIs enabled; Cloud DNS managed zone; service account key (JSON) optional |
# Build the CLI
make cli
# Create a cluster (interactive mode — prompts for all required fields)
./bin/microshift-installer create cluster --dir=./my-cluster
# Or use a pre-written install-config.yaml (see examples/)
./bin/microshift-installer create cluster --dir=./my-cluster
# Destroy
./bin/microshift-installer destroy cluster --dir=./my-cluster| Command | Description |
|---|---|
create cluster --dir=<path> |
Create a new MicroShift cluster |
destroy cluster --dir=<path> |
Destroy a MicroShift cluster |
version |
Print version |
If --dir is not provided, it defaults to ~/.microshift-installer/<cluster-name>/.
Full reference — see examples/install-config.yaml.example for a completed template.
apiVersion: v1 # Required
metadata:
name: my-cluster # Required — used for resource naming
baseDomain: example.com # Required — Route53 zone or Cloud DNS managed zone
cloudProvider: aws # Required — "aws" or "gcp"
ocpVersion: "4.14" # Optional — default: 4.14
pullSecret: '{...}' # Required — inline JSON pull secret
sshKey: | # Required — public SSH key content
ssh-rsa AAAA...
sshPrivateKeyPath: ~/.ssh/id_rsa # Optional — default: ~/.ssh/id_rsa
rhsm:
username: my-user # Required — Red Hat subscription username
password: my-password # Required — Red Hat subscription password
platform:
aws:
region: us-east-2 # Optional — default: us-east-2
instanceType: t2.medium # Optional — default: t2.medium
gcp:
project: my-project # Required when cloudProvider=gcp
region: us-central1 # Optional — default: us-central1
zone: us-central1-a # Optional — default: us-central1-a
machineType: e2-standard-2 # Optional — default: e2-standard-2
bootDiskSizeGB: 30 # Optional — default: 30
credentialsPath: "" # Optional — path to GCP SA key JSON
dnsZoneName: "" # Required for GCP DNS — Cloud DNS managed zone name
network:
vpcCIDR: 10.0.0.0/16 # Optional — default: 10.0.0.0/16
publicSubnetCIDR: 10.0.0.0/20 # Optional — default: 10.0.0.0/20
privateSubnetCIDR: 10.0.16.0/20 # Optional — default: 10.0.16.0/20If no install-config.yaml exists in the asset directory, the installer starts an interactive questionnaire covering all required fields.
The cluster-state.json file tracks every cloud resource. It is critical for destruction — keep it safe alongside the asset directory.
{
"resources": [
{ "name": "vpc", "type": "aws_vpc", "provider": "aws", "id": "vpc-abc123" },
{ "name": "microshift_node", "type": "aws_instance", "provider": "aws", "id": "i-abc123" }
]
}Manage MicroShift clusters declaratively via Custom Resources inside a Kubernetes cluster.
┌──────────────────────────────────────────────┐
│ K8s API Server │
│ │
│ MicroShiftDeployment (CR) │
│ ┌──────────────────────────────┐ │
│ │ spec: │ │
│ │ installConfigRef → ConfigMap│ │
│ │ autoDestroy: true │ │
│ │ status: │ │
│ │ phase: Ready/Failed │ │
│ └──────────┬───────────────────┘ │
│ │ creates/owns │
│ ▼ │
│ MicroShiftProvisioner (CR) │
│ ┌──────────────────────────────┐ │
│ │ spec: │ │
│ │ operation: Create/Destroy │ │
│ │ installConfig: {...} │ │
│ │ status: │ │
│ │ phase: Running/Succeeded │ │
│ │ resources: [...] │ │
│ └──────────┬───────────────────┘ │
│ │ runs async │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Provisioner Controller│──→ AWS/GCP SDK │
│ └──────────────────────┘ │
│ │
│ ConfigMap (install-config.yaml) │
│ Secret (GCP SA Key) │
└──────────────────────────────────────────────┘
The user-facing CR that describes a desired cluster deployment.
apiVersion: cluster-install.io/v1alpha1
kind: MicroShiftDeployment
metadata:
name: my-cluster
spec:
clusterName: my-cluster
installConfigRef:
name: my-cluster-install-config
autoDestroy: trueAn internal CR that manages the actual provisioning operation. Created automatically by the deployment controller.
apiVersion: cluster-install.io/v1alpha1
kind: MicroShiftProvisioner
spec:
clusterName: my-cluster
operation: Create # or "Destroy"
installConfig: "..." # deserialised from ConfigMap
cloudProvider: aws- Create: User creates
MicroShiftDeployment+ ConfigMap → controller createsMicroShiftProvisioner(operation=Create)→ async provisioning → status updated toReady - Destroy (auto): User deletes
MicroShiftDeployment→ finalizer blocks deletion → controller createsMicroShiftProvisioner(operation=Destroy)→ resources torn down → finalizer removed
# 1. Build the operator image
make docker-build IMG=my-registry/microshift-installer:latest
# 2. Push to your registry
make docker-push IMG=my-registry/microshift-installer:latest
# 3. Update config/manager/manager.yaml with your image name
# 4. Deploy to cluster
make deploy
# 5. Create an install-config ConfigMap
kubectl apply -f config/samples/install-config.yaml
# 6. Create a MicroShiftDeployment
kubectl apply -f config/samples/microshiftdeployment_sample.yaml
# 7. Watch progress
kubectl get msd -w
kubectl get msp -wConfigure cloud credentials in the operator's Deployment (config/manager/manager.yaml):
env:
# AWS
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-credentials
key: access-key-id
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-credentials
key: secret-access-key
# GCP
- name: GOOGLE_APPLICATION_CREDENTIALS
value: /etc/gcp/sa-key.json
volumeMounts:
- name: gcp-sa-key
mountPath: /etc/gcp
readOnly: true# CLI binary (to bin/microshift-installer)
make cli
# Operator manager binary (to bin/manager)
make build
# Operator Docker image
make docker-buildmicroshift-installer/
├── cmd/
│ ├── microshift-installer/
│ │ └── main.go ← CLI entry point (cobra)
│ └── manager/
│ └── main.go ← Operator entry point (controller-runtime)
├── api/
│ └── v1alpha1/ ← CRD type definitions
│ ├── groupversion_info.go
│ ├── microshiftdeployment_types.go
│ ├── microshiftprovisioner_types.go
│ └── zz_generated.deepcopy.go
├── controllers/
│ ├── microshiftdeployment_controller.go
│ └── microshiftprovisioner_controller.go
├── config/
│ ├── crd/ ← CRD YAML manifests
│ ├── rbac/ ← RBAC resources
│ ├── manager/ ← Operator Deployment
│ └── samples/ ← Example CRs
├── pkg/
│ ├── types/
│ │ └── installconfig.go ← InstallConfig struct + validation
│ ├── config/
│ │ ├── installconfig.go ← YAML parse/save
│ │ └── interactive.go ← Interactive prompts (survey)
│ ├── asset/
│ │ └── store.go ← Asset directory management
│ ├── state/
│ │ └── state.go ← Cluster resource state (JSON)
│ └── platform/
│ ├── platform.go ← Platform interface
│ ├── aws.go ← AWS: EC2, VPC, Route53 via aws-sdk-go-v2
│ └── gcp.go ← GCP: Compute Engine, DNS via google-cloud-go
├── examples/
│ └── install-config.yaml.example
├── Dockerfile
├── Makefile
├── go.mod / go.sum
└── README.md