Getting started

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.

Prerequisites

1. Install the HyperShift CLI (hypershift) using Go 1.19:

   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

2. Admin access to an OpenShift cluster (version 4.12+) specified by the KUBECONFIG environment variable.
3. The OpenShift CLI (oc) or Kubernetes CLI (kubectl).
4. A valid pull secret file for the quay.io/openshift-release-dev repository.
5. AWS credentials with permissions to create infrastructure for the cluster. You will need:
   • An IAM role ARN with the required permissions
   • STS credentials (session token) that can be generated using aws sts get-session-token

6. A Route53 public zone for cluster DNS records. To create a public zone:

   1 2	BASE_DOMAIN=www.example.com aws route53 create-hosted-zone --name $BASE_DOMAIN --caller-reference $(whoami)-$(date --rfc-3339=date)

   Important

   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.

7. An S3 bucket with public access to host OIDC discovery documents for your clusters. To create the bucket in us-east-1:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   export BUCKET_NAME=your-bucket-name aws s3api create-bucket --bucket $BUCKET_NAME aws s3api delete-public-access-block --bucket $BUCKET_NAME echo '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::${BUCKET_NAME}/*" } ] }' | envsubst > policy.json aws s3api put-bucket-policy --bucket $BUCKET_NAME --policy file://policy.json

   To create the bucket in a region other than us-east-1:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   export BUCKET_NAME=your-bucket-name REGION=us-east-2 aws s3api create-bucket --bucket $BUCKET_NAME \ --create-bucket-configuration LocationConstraint=$REGION \ --region $REGION aws s3api delete-public-access-block --bucket $BUCKET_NAME echo '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::${BUCKET_NAME}/*" } ] }' | envsubst > policy.json aws s3api put-bucket-policy --bucket $BUCKET_NAME --policy file://policy.json

Install HyperShift Operator

Install the HyperShift Operator 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
9

REGION=us-east-1
BUCKET_NAME=your-bucket-name
AWS_CREDS="$HOME/.aws/credentials"

hypershift install \
  --oidc-storage-provider-s3-bucket-name $BUCKET_NAME \
  --oidc-storage-provider-s3-credentials $AWS_CREDS \
  --oidc-storage-provider-s3-region $REGION \
  --enable-defaulting-webhook true

Create a Hosted Cluster

Create a new hosted cluster, specifying the domain of the public zone provided in the Prerequisites.

Set Up AWS Credentials

The HyperShift CLI uses AWS STS (Security Token Service) for authentication. You need:

1. An IAM role with the required permissions to create cluster infrastructure
2. Temporary STS credentials to authenticate

Create an IAM role using the HyperShift CLI. The --aws-creds flag points to the credentials file for your personal IAM user (the one used by the AWS CLI), which HyperShift uses to create the new role:

1
2
3
4
5

# Path to your existing AWS credentials file (for your personal IAM user)
AWS_CREDS="$HOME/.aws/credentials"

# Create a unique role name for your user
hypershift create iam cli-role --aws-creds $AWS_CREDS --name my-hypershift-cli-role

The command will output the role ARN. Save this value for use in subsequent commands:

ROLE_ARN="arn:aws:iam::123456789012:role/my-hypershift-cli-role"

Generate temporary STS credentials:

aws sts get-session-token --output json > sts-creds.json

Create the Cluster

Create the hosted cluster using the STS credentials:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

REGION=us-east-1
CLUSTER_NAME=example
BASE_DOMAIN=example.com
ROLE_ARN="arn:aws:iam::123456789012:role/your-hypershift-role"
STS_CREDS="/tmp/sts-creds.json"
PULL_SECRET="$HOME/pull-secret"

hypershift create cluster aws \
  --name $CLUSTER_NAME \
  --node-pool-replicas=3 \
  --base-domain $BASE_DOMAIN \
  --pull-secret $PULL_SECRET \
  --role-arn $ROLE_ARN \
  --sts-creds $STS_CREDS \
  --region $REGION \
  --generate-ssh

After a few minutes, check the hostedclusters resources in the clusters 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 CLI:

hypershift create kubeconfig

Create Additional NodePools

Create additional NodePools for a cluster by specifying a name, number of replicas and additional information such as instance type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

NODEPOOL_NAME=${CLUSTER_NAME}-work
INSTANCE_TYPE=m5.2xlarge
NODEPOOL_REPLICAS=2

hypershift create nodepool aws \
  --cluster-name $CLUSTER_NAME \
  --namespace clusters \
  --name $NODEPOOL_NAME \
  --replicas $NODEPOOL_REPLICAS \
  --instance-type $INSTANCE_TYPE

Check the status of the NodePool by listing nodepool resources in the clusters namespace:

oc get nodepools --namespace clusters

Scale a NodePool

Manually scale a NodePool using the oc scale command:

1
2
3
4
5
6

NODEPOOL_NAME=${CLUSTER_NAME}-work
NODEPOOL_REPLICAS=5

oc scale nodepool/$NODEPOOL_NAME \
  --namespace clusters \
  --replicas=$NODEPOOL_REPLICAS

Delete a Hosted Cluster

To delete a Hosted Cluster:

hypershift destroy cluster aws \
  --name $CLUSTER_NAME \
  --role-arn $ROLE_ARN \
  --sts-creds $STS_CREDS