---
title: Getting Started
weight: 10
aliases: /hypershift/getting-started/
---

:toc:
:imagesdir: /images
:_content-type: ASSEMBLY
include::modules/comm-attributes.adoc[]

[id="deploying-hypershift-pattern"]
== Deploying the hosted control plane (HyperShift) pattern

.Prerequisites

* An OpenShift cluster
 ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console].
 ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*.
* A GitHub account.
* Additional installation tool dependencies. For details, see link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].
* AWS account with permissions to create S3 buckets.
+
[WARNING]
====
You must have a public s3 bucket for OIDC discovery. If you do not have one, set `global.hypershift.createBucket` to `true` in the `values-hypershift.yaml` file to create one during the deployment.

You can also run `./pattern.sh make create-bucket BUCKET_NAME=<bucket-name> REGION=<region>` to create the bucket before running `./pattern.sh make install`.
====

[id="preparing-for-deployment"]
== Preparing for deployment
.Procedure

. Fork the link:https://github.com/validatedpatterns-sandbox/hypershift[hypershift] repository on GitHub. You must fork the repository because your fork is updated as part of the GitOps and DevOps processes.

. Clone the forked copy of this repository.
+
[source,terminal]
----
$ git clone git@github.com:validatedpatterns-sandbox/hypershift.git
----

. Go to your repository: Ensure you are in the root directory of your Git repository by using:
+
[source,terminal]
----
$ cd /path/to/your/repository
----

. Run the following command to set the upstream repository:
+
[source,terminal]
----
$ git remote add -f upstream git@github.com:validatedpatterns-sandbox/hypershift.git
----

. Verify the setup of your remote repositories by running the following command:
+
[source,terminal]
----
$ git remote -v
----
+
.Example output
+
[source,terminal]
----
origin	git@github.com:kquinn1204/hypershift.git (fetch)
origin	git@github.com:kquinn1204/hypershift.git (push)
upstream	git@github.com:validatedpatterns/hyperShift.git (fetch)
upstream	git@github.com:validatedpatterns/hypershift.git (push)
----

. Make a local copy of secrets template outside of your repository to hold credentials for the pattern.
+
[WARNING]
====
Do not add, commit, or push this file to your repository. Doing so may expose personal credentials to GitHub.
====
+
Run the following commands:
+
[source,terminal]
----
$ cp values-secret.yaml.template ~/values-secret-hypershift.yaml
----

. Populate this file with your secrets, the defaults for AWS credentials is `~/.aws/credentials`. The GitHub `oauth` credentials can remain commented out:
+
[source,terminal]
----
$ vi ~/values-secret-hypershift.yaml
----

. Create and switch to a new branch named `my-branch`, by running the following command:
+
[source,terminal]
----
$ git checkout -b my-branch
----

. Edit the `values-hypershift.yaml` file to provide your s3 bucket information.
+
[source,terminal]
----
$ vi values-hypershift.yaml
----
+
.Example
[source,terminal]
----
# Override values for HyperShift 
# Define the s3 bucket information  
global:
  hypershift:
# Set createBucket to true to create a new S3 bucket for hosting hosted control plane assets
    createBucket: true 
    oidc:
# OIDC bucket information: provide region and bucketName
      region: ''
      bucketName: ''

# Define the oauth provider for the management cluster    
# register a GitHub oAuth application: https://github.com/settings/applications/new
# configure oauth provider: https://docs.openshift.com/container-platform/4.15/authentication/understanding-identity-provider.html
#
# The default configuration uses github as the provider
  oauth:
    type: GitHub
    secretName: ocp-github-oauth
    github:
      clientID: #clientID of the registered GitHub oAuth Application
      orgs:
      - name: #list of github authorized organizations

# Set rbac.create to false if you want to skip creation of role/rolebinding.
rbac:
  create: false
# Provide a list of users to add to the clusterrolebinding
  users: []
----

[NOTE]
====
A clusterrole is provided that grants the necessary permissions to the users specified in the `values-hypershift.yaml` file to manage the lifecycle of hosted control planes.
====
+
. Add the changes to the staging area by running the following command:
+
[source,terminal]
----
$ git add -u
----

. Commit the changes by running the following command:
+
[source,terminal]
----
$ git commit -m "updates to hypershift pattern"
----

. Push the changes to your forked repository:
+
[source,terminal]
----
$ git push origin my-branch
----

The preferred way to install this pattern is by using the `./pattern.sh` script. 

[id="deploying-cluster-using-patternsh-file"]
== Deploying the pattern by using the pattern.sh file

To deploy the pattern by using `pattern.sh`, complete the following steps:

. Log in to your cluster by following this procedure:

.. Obtain an API token by visiting link:https://oauth-openshift.apps.<your-cluster>.<domain>/oauth/token/request[https://oauth-openshift.apps.<your-cluster>.<domain>/oauth/token/request].

.. Log in to the cluster by running the following command: 
+
[source,terminal]
----
$ oc login --token=<retrieved-token> --server=https://api.<your-cluster>.<domain>:6443
----
+
Or log in by running the following command:
+
[source,terminal]
----
$ export KUBECONFIG=~/<path_to_kubeconfig>
----

. Deploy the pattern to your cluster. Run the following command:
+
[source,terminal]
----
$ ./pattern.sh make install
----

.Verification

. Verify that the Operators have been installed. Navigate to *Operators → Installed Operators* page in the OpenShift Container Platform web console, 
+
.hypershift-operators
image::/images/hypershift/hypershift-ops.png[hypershift-operators,title="Hosted control plane Operators"]

. Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. 
+
.hypershif-operators-applications
image::/images/hypershift/hypershift-ops-applications.png[hypershift-ops-applications,title="A Hosted control plane applications"]

As part of installing by using the script `pattern.sh` pattern, HashiCorp Vault is installed. Running `./pattern.sh make install` also calls the `load-secrets` makefile target. This `load-secrets` target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repository to try to generate random secrets.

For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault].

At this point, a management cluster is deployed and the pattern is ready to be used to create control planes as pods on a management cluster. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/hosted_control_planes/index[Hosted control planes].