Extract OpenShift installer from release image and create an OCP cluster
Creates OpenShift clusters by extracting installers from release images and automating setup.
/plugin marketplace add openshift-eng/ai-helpers/plugin install openshift@ai-helpers[release-image] [platform] [options]openshift:create-cluster
/openshift:create-cluster [release-image] [platform] [options]
The create-cluster command automates the process of extracting the OpenShift installer from a release image (if not already present) and creating a new OpenShift Container Platform (OCP) cluster. It handles installer extraction from OCP release images, configuration preparation, and cluster creation in a streamlined workflow.
This command is useful for:
IMPORTANT: This is a last resort tool for advanced use cases. For most development workflows, you should use one of these better alternatives:
Cluster Bot: Request ephemeral test clusters without managing infrastructure
Gangway
Multi-PR Testing in CI: Test multiple dependent PRs together using /test-with commands
Only use this command when:
Note: This command requires significant setup (cloud credentials, pull secrets, DNS configuration, understanding of OCP versions). If you're new to OpenShift development, start with Cluster Bot or Gangway instead.
Before using this command, ensure you have:
OpenShift CLI (oc): Required to extract the installer from the release image
brew install openshift-cli (macOS)oc versionCloud Provider Credentials configured for your chosen platform:
~/.aws/credentials configured with appropriate permissionsaz login)Pull Secret: Download from Red Hat Console
Domain/DNS Configuration:
The command accepts arguments in multiple ways:
/openshift:create-cluster [release-image] [platform]
If arguments are not provided, the command will interactively prompt for:
release-image (required): OpenShift release image to extract the installer from
quay.io/openshift-release-dev/ocp-release:4.21.0-ec.2-x86_64registry.ci.openshift.org/ocp/release:4.21.0-0.ci-2025-10-27-031915quay.io/openshift-release-dev/ocp-release:4.20.1-x86_64platform (optional): Target platform for the cluster
aws: Amazon Web Servicesazure: Microsoft Azuregcp: Google Cloud Platformvsphere: VMware vSphereopenstack: OpenStacknone: Bare metal / platform-agnosticcluster-name (optional): Name for the cluster
ocp-clusterbase-domain (required): Base domain for the cluster
example.com → Cluster API will be api.{cluster-name}.{base-domain}pull-secret (required): Path to pull secret file
installer-dir (optional): Directory to store/find installer binaries
~/.openshift-installersThe command performs the following steps:
Check that required tools and credentials are available:
oc CLI is installed and availableIf any prerequisites are missing, provide clear instructions on how to configure them.
If not provided as an argument, prompt the user for the OpenShift release image:
Please provide the OpenShift release image:
Examples:
- Production release: quay.io/openshift-release-dev/ocp-release:4.21.0-ec.2-x86_64
- CI build: registry.ci.openshift.org/ocp/release:4.21.0-0.ci-2025-10-27-031915
- Stable release: quay.io/openshift-release-dev/ocp-release:4.20.1-x86_64
Release image:
Store the user's input as $RELEASE_IMAGE.
Extract version from image for naming:
# Parse version from image tag (e.g., "4.21.0-ec.2" or "4.21.0-0.ci-2025-10-27-031915")
VERSION=$(echo "$RELEASE_IMAGE" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+[^"]*' | head -1)
INSTALLER_DIR="${installer-dir:-$HOME/.openshift-installers}"
INSTALLER_PATH="$INSTALLER_DIR/openshift-install-${VERSION}"
Check if installer directory exists:
$INSTALLER_DIR does not exist:
$INSTALLER_DIR does not exist. Would you like to create it?"mkdir -p "$INSTALLER_DIR"Check if the installer already exists at $INSTALLER_PATH:
"$INSTALLER_PATH" version
Extract installer from release image:
Verify oc CLI is available:
if ! command -v oc &> /dev/null; then
echo "Error: 'oc' CLI not found. Please install the OpenShift CLI."
exit 1
fi
Extract the installer binary:
oc adm release extract \
--tools \
--from="$RELEASE_IMAGE" \
--to="$INSTALLER_DIR"
This extracts the openshift-install binary and other tools from the release image.
Locate and rename the extracted installer:
# The extract command creates a tar.gz with the tools
# Find the most recently extracted openshift-install tar (compatible with both GNU and BSD find)
INSTALLER_TAR=$(find "$INSTALLER_DIR" -name "openshift-install-*.tar.gz" -type f -exec ls -t {} + | head -1)
# Extract from tar and rename
cd "$INSTALLER_DIR"
tar -xzf "$INSTALLER_TAR" openshift-install
mv openshift-install "openshift-install-${VERSION}"
chmod +x "openshift-install-${VERSION}"
# Clean up the tar file
rm "$INSTALLER_TAR"
Verify the installer:
"$INSTALLER_PATH" version
Expected output should show the version matching $VERSION.
Create a clean installation directory:
INSTALL_DIR="${cluster-name}-install-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$INSTALL_DIR"
cd "$INSTALL_DIR"
IMPORTANT: Do NOT run the installer interactively. Instead, collect all required information from the user and generate the install-config.yaml programmatically.
Step 5.1: Collect Information
Prompt the user for the following information (if not already provided as arguments):
SSH Public Key:
ls -la ~/.ssh/*.pub~/.ssh/id_rsa.pubPlatform (if not provided as argument):
Platform-specific details:
Base Domain:
Cluster Name:
ocp-clusterPull Secret:
~/pull-secret.txt or ~/Downloads/pull-secret.txtStep 5.2a: GCP Service Account Setup (Only for GCP platform)
If the platform is GCP, the installer requires a service account JSON file with appropriate permissions. Present the user with two options:
Ask the user: "Do you want to use an existing service account JSON file or create a new one?"
Option 1: Use Existing Service Account
If the user chooses to use an existing service account:
$GCP_SERVICE_ACCOUNT_PATHexport GOOGLE_APPLICATION_CREDENTIALS="$GCP_SERVICE_ACCOUNT_PATH"
Option 2: Create New Service Account
If the user chooses to create a new service account:
Verify gcloud CLI is installed:
if ! command -v gcloud &> /dev/null; then
echo "Error: 'gcloud' CLI not found. Please install the Google Cloud SDK."
echo "Visit: https://cloud.google.com/sdk/docs/install"
exit 1
fi
Prompt for Kerberos ID:
$KERBEROS_IDSet service account name:
SERVICE_ACCOUNT_NAME="${KERBEROS_ID}-development"
Create the service account:
echo "Creating service account: $SERVICE_ACCOUNT_NAME"
gcloud iam service-accounts create "$SERVICE_ACCOUNT_NAME" --display-name="$SERVICE_ACCOUNT_NAME"
Extract service account details:
# Get service account information
SERVICE_ACCOUNT_JSON="$(gcloud iam service-accounts list --format json | jq -r '.[] | select(.name | match("/\(env.SERVICE_ACCOUNT_NAME)@"))')"
SERVICE_ACCOUNT_EMAIL="$(jq -r .email <<< "$SERVICE_ACCOUNT_JSON")"
PROJECT_ID="$(jq -r .projectId <<< "$SERVICE_ACCOUNT_JSON")"
echo "Service Account Email: $SERVICE_ACCOUNT_EMAIL"
echo "Project ID: $PROJECT_ID"
Grant required permissions:
echo "Granting IAM roles to service account..."
while IFS= read -r ROLE_TO_ADD ; do
echo "Adding role: $ROLE_TO_ADD"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--condition="None" \
--member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
--role="$ROLE_TO_ADD"
done << 'END_OF_ROLES'
roles/compute.admin
roles/iam.securityAdmin
roles/iam.serviceAccountAdmin
roles/iam.serviceAccountKeyAdmin
roles/iam.serviceAccountUser
roles/storage.admin
roles/dns.admin
roles/compute.loadBalancerAdmin
roles/iam.roleAdmin
END_OF_ROLES
echo "All roles granted successfully."
Create and download service account key:
KEY_FILE="${HOME}/.gcp/${SERVICE_ACCOUNT_NAME}-key.json"
mkdir -p "$(dirname "$KEY_FILE")"
echo "Creating service account key..."
gcloud iam service-accounts keys create "$KEY_FILE" \
--iam-account="$SERVICE_ACCOUNT_EMAIL"
echo "Service account key saved to: $KEY_FILE"
Set environment variable:
export GOOGLE_APPLICATION_CREDENTIALS="$KEY_FILE"
echo "GOOGLE_APPLICATION_CREDENTIALS set to: $KEY_FILE"
Store PROJECT_ID for later use in install-config.yaml generation.
Step 5.2: Generate install-config.yaml
Create the install-config.yaml file programmatically based on collected information:
# Read SSH public key
SSH_KEY=$(cat "$SSH_KEY_PATH")
# Read pull secret
PULL_SECRET=$(cat "$PULL_SECRET_PATH")
# Generate install-config.yaml
cat > install-config.yaml <<EOF
apiVersion: v1
baseDomain: ${BASE_DOMAIN}
metadata:
name: ${CLUSTER_NAME}
compute:
- name: worker
replicas: 3
controlPlane:
name: master
replicas: 3
networking:
networkType: OVNKubernetes
clusterNetwork:
- cidr: 10.128.0.0/14
hostPrefix: 23
serviceNetwork:
- 172.30.0.0/16
platform:
${PLATFORM}:
region: ${REGION}
pullSecret: '${PULL_SECRET}'
sshKey: '${SSH_KEY}'
EOF
Platform-specific configurations:
For AWS:
platform:
aws:
region: us-east-1
For Azure:
platform:
azure:
region: centralus
baseDomainResourceGroupName: ${RESOURCE_GROUP_NAME}
cloudName: AzurePublicCloud
For GCP:
platform:
gcp:
projectID: ${PROJECT_ID}
region: us-central1
For None/Baremetal:
platform:
none: {}
IMPORTANT: Always backup install-config.yaml after creation:
cp install-config.yaml install-config.yaml.backup
The installer consumes this file, so the backup is essential for reference.
Run the installer:
"$INSTALLER_PATH" create cluster --dir=.
Monitor the installation progress. This typically takes 30-45 minutes.
Once installation completes:
Display kubeconfig location:
Kubeconfig: $INSTALL_DIR/auth/kubeconfig
Display cluster credentials:
Console URL: https://console-openshift-console.apps.${cluster-name}.${base-domain}
Username: kubeadmin
Password: (from $INSTALL_DIR/auth/kubeadmin-password)
Export KUBECONFIG (offer to add to shell profile):
export KUBECONFIG="$PWD/auth/kubeconfig"
Verify cluster access:
oc get nodes
oc get co # cluster operators
Save cluster information to a summary file:
Cluster: ${cluster-name}
Version: ${VERSION}
Release Image: ${RELEASE_IMAGE}
Platform: ${platform}
Console: https://console-openshift-console.apps.${cluster-name}.${base-domain}
API: https://api.${cluster-name}.${base-domain}:6443
Kubeconfig: $INSTALL_DIR/auth/kubeconfig
Created: $(date)
If installation fails:
.openshift_install.log"$INSTALLER_PATH" destroy cluster --dir=.
/openshift:create-cluster
The command will prompt for release image and all necessary information.
/openshift:create-cluster quay.io/openshift-release-dev/ocp-release:4.21.0-ec.2-x86_64 aws
/openshift:create-cluster registry.ci.openshift.org/ocp/release:4.21.0-0.ci-2025-10-27-031915 gcp
To destroy the cluster after testing:
cd $INSTALL_DIR
"$INSTALLER_PATH" destroy cluster --dir=.
WARNING: This will permanently delete all cluster resources.
Pull secret not found:
Insufficient cloud quotas:
DNS issues:
SSH key not found:
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsaUnauthorized access to release image:
error: unable to read image quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...: unauthorized: access to the requested resource is not authorizedquay.io/openshift-release-dev/ocp-v4.0-art-dev you can get the pull secret from https://console.redhat.com/openshift/install/pull-secret and save it in a file and provide it here.quay.io/openshift-release-dev/ocp-release:4.21.0-ec.2-x86_64)