HyperShift is middleware for hosting OpenShift control planes at scale that solves for cost and time to provision, as well as portability across cloud service providers with strong separation of concerns between management and workloads. Clusters are fully compliant OpenShift Container Platform (OCP) clusters and are compatible with standard OCP and Kubernetes toolchains.
This guide will lead you through the process of creating a new hosted cluster. Throughout the instructions, shell variables are used to indicate values that you should adjust to your own environment.
The HyperShift CLI (
Install it using Go 1.18:
1 2 3 4
git clone https://github.com/openshift/hypershift.git cd hypershift make build sudo install -m 0755 bin/hypershift /usr/local/bin/hypershift
Admin access to an OpenShift cluster (version 4.8+) specified by the
- The OpenShift CLI (
oc) or Kubernetes CLI (
- A valid pull secret file for the
- An AWS credentials file with permissions to create infrastructure for the cluster.
A Route53 public zone for cluster DNS records.
To create a public zone:
BASE_DOMAIN=www.example.com aws route53 create-hosted-zone --name $BASE_DOMAIN --caller-reference $(whoami)-$(date --rfc-3339=date)
To access applications in your guest clusters, the public zone must be routable. If the public zone exists, skip this step. Otherwise, the public zone will affect the existing functions.
An S3 bucket with public access to host OIDC discovery documents for your clusters.
To create the bucket (in us-east-1):
BUCKET_NAME=your-bucket-name aws s3api create-bucket --acl public-read --bucket $BUCKET_NAME
To create the bucket in a region other than us-east-1:
1 2 3 4 5
BUCKET_NAME=your-bucket-name REGION=us-east-2 aws s3api create-bucket --acl public-read --bucket $BUCKET_NAME \ --create-bucket-configuration LocationConstraint=$REGION \ --region $REGION
Before you begin
Install HyperShift into the management cluster, specifying the OIDC bucket, its region and credentials to access it (see Prerequisites):
1 2 3 4 5 6 7 8
Create a HostedCluster
Create a new cluster, specifying the domain of the public zone provided in the Prerequisites:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
The cluster name (
--name) must be unique within the base domain to
avoid unexpected and conflicting cluster management behavior.
A default NodePool will be created for the cluster with 3 replicas per the
The default NodePool name will be a combination of your cluster name and zone name for
example-us-east-1a). For other providers, the default NodePool
name will be the same as the cluster name.
--generate-ssh flag is not strictly necessary but it will help in
debugging why a node has not joined your cluster.
After a few minutes, check the
hostedclusters resources in the
namespace and when ready it will look similar to the following:
oc get --namespace clusters hostedclusters NAME VERSION KUBECONFIG PROGRESS AVAILABLE PROGRESSING MESSAGE example 4.12.0 example-admin-kubeconfig Completed True False The hosted control plane is available oc get nodepools --namespace clusters NAME CLUSTER DESIRED NODES CURRENT NODES AUTOSCALING AUTOREPAIR VERSION UPDATINGVERSION UPDATINGCONFIG MESSAGE example-us-east-1a example 2 2 False False 4.12.0
Eventually the cluster's kubeconfig will become available and can be printed to
standard out using the
hypershift create kubeconfig
Create additional NodePools for a cluster by specifying a name, number of replicas and additional information such as instance type.
Create a NodePool:
1 2 3 4 5 6 7 8 9 10
The default infrastructure created for the cluster during Create a HostedCluster lives in a single availability zone. Any additional NodePool created for that cluster must be in the same availability zone and subnet.
Check the status of the NodePool by listing
nodepool resources in the
oc get nodepools --namespace clusters
Scale a NodePool
Manually scale a NodePool using the
oc scale command:
1 2 3 4 5 6
Delete a HostedCluster
To delete a HostedCluster:
hypershift destroy cluster aws \ --name $CLUSTER_NAME \ --aws-creds $AWS_CREDS
To clean up cloud resources that may have been created by the HostedCluster during its lifetime, add
hypershift destroy cluster aws \ --name $CLUSTER_NAME \ --aws-creds $AWS_CREDS \ --destroy-cloud-resources