--- title: Using HyperShift weight: 10 aliases: /hypershift/using-hcp/ --- :toc: :imagesdir: /images :_content-type: ASSEMBLY include::modules/comm-attributes.adoc[] [id="using-hypershift"] == Using HyperShift .Assumptions * You have an existing OpenShift cluster deployed * You have installed the {hcp-pattern} on your OpenShift cluster by following the link:/hypershift/getting-started/[Getting Started] guide. ** Or you have multicluster-engine and hypershift components installed on your OpenShift cluster. * Existing IAM role with attached policies that allow for provisioning/destroy clusters on AWS. ** Or you have permissions to create IAM roles and policies on AWS. .Prerequisites * The `hcp` CLI installed. Download from your cluster link:https://hcp-cli-download-multicluster-engine.apps../linux/amd64/hcp.tar.gz[https://hcp-cli-download-multicluster-engine.apps../linux/amd64/hcp.tar.gz] * The `oc` CLI installed. For instructions, see link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI]. * Ansible is installed on your system, with `kuberenetes.core amazon.aws collections` * Pull secret obtained from link:https://console.redhat.com/openshift/install/pull-secret[OpenShift Console] and converted to json format. === Using HyperShift Automation Automation for HyperShift is provided through the link:https://github.com/validatedpatterns/hypershift-automation[hypershift-automation] repository. This repository uses Ansible to create and destroy hosted control planes on AWS. .Procedure . Fork the link:https://github.com/validatedpatterns/hypershift-automation[hypershift-automation] repository on GitHub. . Clone the forked copy of this repository. + [source,terminal] ---- $ git clone git@github.com:validatedpatterns/hypershift-automation.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 ---- + [WARNING] ==== You must have a an IAM role with the required policies attached to provision clusters on AWS. ==== + . Create IAM role and policies: + [source,terminal] ---- $ vi hcp/defaults/main.yml ---- + .Example [source,terminal] ---- iam: hcp_role_name: democluster_hcp_role hcp_policy_name: democluster_hcp_policy hcp_users: #- list of users to bind to IAM policy - - ---- . Run the following command to create the IAM role and policies: + [source,terminal] ---- $ make iam ---- . Edit the `vars.yml` file: + [source,terminal] ---- vi vars.yml ---- + .Example [source,terminal] ---- #Actions -e create=true "creates a cluster" -e destroy=true "destroys a cluster" # Note: These are overriden by make targets create: false destroy: false #Create IAM # Note: Overriden by make target create_iam: false # Base domain - constant for all clusters domain: aws.validatedpatterns.io # Clusters list - Define multiple clusters with different characteristics # Each cluster can have its own region, instance_type, image (version), replicas, etc. clusters: # Example: Deploy a single node cluster to one availability zone # Only a single node will be provisioned - name: democluster count: 1 region: us-east-1 spread_across_availability_zones: false replicas: 1 instance_type: m5.4xlarge image: default # Example: Deploy 2 clusters to each availability zone with 2 replicas per zone that are ocp version 4.18.9 # us-west-1 has 2 az's: therefore, a total of 8 nodes will be provisioned (2 replicas us-west-1a, 2 replicas us-west-1b per cluster) - name: cluster1 # cluster1, cluster1-1 will be created count: 2 region: us-west-1 spread_across_availability_zones: true replicas: 1 instance_type: m5.xlarge image: 4.18.9 ---- . Run the following command to create the hosted control plane: + [source,terminal] ---- $ make build ---- + This will take some time to create the hosted control plane and nodepool configuration. . In the OpenShift container platform web console select *All Clusters* to display the *Cluster list*. A screen similar to the following is displayed: + .hypershift-cluster-list image::/images/hypershift/hypershift-cluster-list.png[hypershift-cluster-list,title="Hosted control plane cluster list"] . Select for example the *democluster* to display the *Cluster details* page. A screen similar to the following is displayed: + .hypershift-cluster-details image::/images/hypershift/hypershift-cluster-details.png[hypershift-cluster-details,title="Hosted control plane cluster details"] . Click *Download kubeconfig* to download the `kubeconfig` file for the hosted control plane. .Verification . Export the management cluster kubeconfig: + [source,terminal] ---- $ export MGMT_KUBECONFIG= ---- . Run this command to find the `node-pool-name` for your cluster: + [source,terminal] ---- $ oc --kubeconfig="$MGMT_KUBECONFIG" get np -A ---- + .Example output [source,terminal] ---- NAMESPACE NAME CLUSTER DESIRED NODES CURRENT NODES AUTOSCALING AUTOREPAIR VERSION UPDATINGVERSION UPDATINGCONFIG MESSAGE clusters democluster-us-east-1a democluster 1 1 False False 4.20.8 False False ---- . Run this command to export the downloaded `kubeconfig` file for your hosted control plane: + [source,terminal] ---- $ export HCP_KUBECONFIG= ---- . Use the `kubeconfig` file to view the cluster Operators of the hosted cluster. Enter the following command: + [source,terminal] ---- $ oc --kubeconfig="$HCP_KUBECONFIG" get co ---- + .Example output [source,terminal] ---- NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE console 4.20.8 True False False 57m csi-snapshot-controller 4.20.8 True False False 66m dns 4.20.8 True False False 57m image-registry 4.20.8 True False False 57m ingress 4.20.8 True False False 57m insights 4.20.8 True False False 58m kube-apiserver 4.20.8 True False False 66m kube-controller-manager 4.20.8 True False False 66m kube-scheduler 4.20.8 True False False 66m kube-storage-version-migrator 4.20.8 True False False 58m monitoring 4.20.8 True False False 55m network 4.20.8 True False False 65m node-tuning 4.20.8 True False False 60m openshift-apiserver 4.20.8 True False False 66m openshift-controller-manager 4.20.8 True False False 66m openshift-samples 4.20.8 True False False 57m operator-lifecycle-manager 4.20.8 True False False 66m operator-lifecycle-manager-catalog 4.20.8 True False False 65m operator-lifecycle-manager-packageserver 4.20.8 True False False 66m service-ca 4.20.8 True False False 58m storage 4.20.8 True False False 60m ---- . View the running pods on your hosted cluster by entering the following command: + [source,terminal] ---- $ oc --kubeconfig="$HCP_KUBECONFIG" get pods -A ---- + .Example output [source,terminal] ---- NAMESPACE NAME READY STATUS RESTARTS AGE kube-system konnectivity-agent-56gh5 1/1 Running 0 66m kube-system kube-apiserver-proxy-ip-10-0-129-28.ec2.internal 1/1 Running 0 66m open-cluster-management-agent-addon cluster-proxy-proxy-agent-7c7666c8f8-9d2xb 3/3 Running 0 64m open-cluster-management-agent-addon klusterlet-addon-workmgr-56c67649b6-8flx7 1/1 Running 0 64m open-cluster-management-agent-addon managed-serviceaccount-addon-agent-56d8f7c4bd-krtwt 1/1 Running 0 64m openshift-cluster-csi-drivers aws-ebs-csi-driver-node-tvgt9 3/3 Running 0 66m openshift-cluster-node-tuning-operator tuned-kmlsm 1/1 Running 0 66m openshift-cluster-samples-operator cluster-samples-operator-6895b9d4c7-nsm54 2/2 Running 0 64m openshift-console-operator console-operator-67d5f87dcc-hdv5j 1/1 Running 2 (64m ago) 64m openshift-console console-fcb9d74fc-5jkfx 1/1 Running 0 61m openshift-console downloads-57848c99-8t8xn 1/1 Running 0 64m openshift-dns dns-default-n62b6 2/2 Running 0 65m openshift-dns node-resolver-25vsw 1/1 Running 0 66m openshift-image-registry image-registry-5778996bc4-v4dw6 1/1 Running 1 (63m ago) 64m openshift-image-registry node-ca-qf4fv 1/1 Running 0 66m openshift-ingress-canary ingress-canary-rlz5k 1/1 Running 0 65m openshift-ingress router-default-7fc88ff765-88zt6 1/1 Running 0 64m openshift-insights insights-operator-567c5dd9fc-vhkr5 1/1 Running 1 (63m ago) 64m openshift-kube-storage-version-migrator-operator kube-storage-version-migrator-operator-5d64f77d9f-tbrmm 1/1 Running 1 (63m ago) 64m openshift-kube-storage-version-migrator migrator-76b9bc6b54-mjwwn 1/1 Running 0 64m openshift-machine-config-operator kube-rbac-proxy-crio-ip-10-0-129-28.ec2.internal 1/1 Running 0 66m openshift-monitoring alertmanager-main-0 6/6 Running 0 62m openshift-monitoring cluster-monitoring-operator-6589b986c8-bjb2t 1/1 Running 0 64m openshift-monitoring kube-state-metrics-575c55f885-xcwvp 3/3 Running 0 63m openshift-monitoring metrics-server-766fb8749c-qmbkp 1/1 Running 0 63m openshift-monitoring monitoring-plugin-5567ddf44-vgrwx 1/1 Running 0 63m openshift-monitoring node-exporter-gh76w 2/2 Running 0 63m openshift-monitoring openshift-state-metrics-7466fd7977-hqmwv 3/3 Running 0 63m openshift-monitoring prometheus-k8s-0 6/6 Running 0 62m openshift-monitoring prometheus-operator-5cf88995b6-sqqfq 2/2 Running 0 64m openshift-monitoring prometheus-operator-admission-webhook-7d744487ff-8xb7b 1/1 Running 0 64m openshift-monitoring telemeter-client-857df5b745-9v579 3/3 Running 0 62m openshift-monitoring thanos-querier-585746b745-thnfc 6/6 Running 0 63m openshift-multus multus-additional-cni-plugins-njkgb 1/1 Running 0 66m openshift-multus multus-k6ggs 1/1 Running 0 66m openshift-multus network-metrics-daemon-45wq7 2/2 Running 0 66m openshift-network-console networking-console-plugin-78b59bd487-ms4c7 1/1 Running 0 64m openshift-network-diagnostics network-check-source-7fbf9dfccb-ddvld 1/1 Running 0 64m openshift-network-diagnostics network-check-target-vvktk 1/1 Running 0 66m openshift-network-operator iptables-alerter-5s96x 1/1 Running 0 65m openshift-ovn-kubernetes ovnkube-node-9rsw4 8/8 Running 0 66m openshift-service-ca-operator service-ca-operator-7b9f58bd4b-b62m6 1/1 Running 1 (63m ago) 64m openshift-service-ca service-ca-554d4b766c-82h22 1/1 Running 0 64m ----