Skip to content

Commit 77c5913

Browse files
mbaldessarimbaldessari
authored
Merge pull request #558 from kquinn1204/TELCODOCS-2245
TELCODOCS-2245 Updating hypershift vp docs
2 parents f78f31a + 4b20b47 commit 77c5913

File tree

5 files changed

+393
-0
lines changed

5 files changed

+393
-0
lines changed

Diff for: ‎content/patterns/hypershift/getting-started.adoc

+393
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,393 @@
1+
---
2+
title: Getting Started
3+
weight: 10
4+
aliases: /hypershift/getting-started/
5+
---
6+
7+
:toc:
8+
:imagesdir: /images
9+
:_content-type: ASSEMBLY
10+
include::modules/comm-attributes.adoc[]
11+
12+
[id="deploying-hypershift-pattern"]
13+
== Deploying the hosted control plane (HyperShift) pattern
14+
15+
.Prerequisites
16+
17+
* An OpenShift cluster
18+
** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console].
19+
** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*.
20+
* A GitHub account with a personal access token that has repository read and write permissions.
21+
* The Helm binary, for instructions, see link:https://helm.sh/docs/intro/install/[Installing Helm]
22+
* Additional installation tool dependencies. For details, see link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].
23+
24+
It is desirable to have a cluster for deploying the GitOps management hub assets and a separate cluster(s) for the managed cluster(s).
25+
26+
[id="preparing-for-deployment"]
27+
== Preparing for deployment
28+
.Procedure
29+
30+
. 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.
31+
32+
. Clone the forked copy of this repository.
33+
+
34+
[source,terminal]
35+
----
36+
$ git clone [email protected]:validatedpatterns-sandbox/hypershift.git
37+
----
38+
39+
. Go to your repository: Ensure you are in the root directory of your Git repository by using:
40+
+
41+
[source,terminal]
42+
----
43+
$ cd /path/to/your/repository
44+
----
45+
46+
. Run the following command to set the upstream repository:
47+
+
48+
[source,terminal]
49+
----
50+
$ git remote add -f upstream [email protected]:validatedpatterns-sandbox/hypershift.git
51+
----
52+
53+
. Verify the setup of your remote repositories by running the following command:
54+
+
55+
[source,terminal]
56+
----
57+
$ git remote -v
58+
----
59+
+
60+
.Example output
61+
+
62+
[source,terminal]
63+
----
64+
origin [email protected]:kquinn1204/ansible-edge-gitops.git (fetch)
65+
origin [email protected]:kquinn1204/ansible-edge-gitops.git (push)
66+
upstream [email protected]:validatedpatterns/ansible-edge-gitops.git (fetch)
67+
upstream [email protected]:validatedpatterns/ansible-edge-gitops.git (push)
68+
----
69+
70+
. Make a local copy of secrets template outside of your repository to hold credentials for the pattern.
71+
+
72+
[WARNING]
73+
====
74+
Do not add, commit, or push this file to your repository. Doing so may expose personal credentials to GitHub.
75+
====
76+
+
77+
Run the following commands:
78+
+
79+
[source,terminal]
80+
----
81+
$ cp values-secret.yaml.template ~/values-secret.yaml
82+
----
83+
84+
. Populate this file with your secrets, the defaults for AWS credentials is `~/.aws/credentials`. The GitHub `oauth` credentials can remain commented out:
85+
+
86+
[source,terminal]
87+
----
88+
$ vi ~/values-secret.yaml
89+
----
90+
91+
. Create and switch to a new branch named `my-branch`, by running the following command:
92+
+
93+
[source,terminal]
94+
----
95+
$ git checkout -b my-branch
96+
----
97+
98+
. Edit the `values-hypershift.yaml` file to create a S3 bucket.
99+
+
100+
[source,terminal]
101+
----
102+
$ vi values-hypershift.yaml
103+
----
104+
+
105+
.Example
106+
[source,terminal]
107+
----
108+
global:
109+
s3:
110+
# Should the pattern create the s3 bucket(true), or bring your own (false).
111+
createBucket: true
112+
113+
# What region should the bucket be created in.
114+
region: us-east-1
115+
116+
# Enter the name of your bucket (bucket names are globally unique)
117+
bucketName: <aws-iam-username-hcp>
118+
119+
# Any additional tags to add to a bucket created by the pattern
120+
additionalTags:
121+
bucketOwner: <aws-iam-username>
122+
lifecycle: keep
123+
----
124+
125+
. Add the changes to the staging area by running the following command:
126+
+
127+
[source,terminal]
128+
----
129+
$ git add -u
130+
----
131+
132+
. Commit the changes by running the following command:
133+
+
134+
[source,terminal]
135+
----
136+
$ git commit -m "updates to hypershift pattern"
137+
----
138+
139+
. Push the changes to your forked repository:
140+
+
141+
[source,terminal]
142+
----
143+
$ git push origin my-branch
144+
----
145+
146+
The preferred way to install this pattern is by using the script `./pattern.sh` script.
147+
148+
[id="deploying-cluster-using-patternsh-file"]
149+
== Deploying the pattern by using the pattern.sh file
150+
151+
To deploy the pattern by using the `pattern.sh` file, complete the following steps:
152+
153+
. Log in to your cluster by following this procedure:
154+
155+
.. 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].
156+
157+
.. Log in to the cluster by running the following command:
158+
+
159+
[source,terminal]
160+
----
161+
$ oc login --token=<retrieved-token> --server=https://api.<your-cluster>.<domain>:6443
162+
----
163+
+
164+
Or log in by running the following command:
165+
+
166+
[source,terminal]
167+
----
168+
$ export KUBECONFIG=~/<path_to_kubeconfig>
169+
----
170+
171+
. Deploy the pattern to your cluster. Run the following command:
172+
+
173+
[source,terminal]
174+
----
175+
$ ./pattern.sh make install
176+
----
177+
178+
.Verification
179+
180+
. Verify that the Operators have been installed. Navigate to *Operators → Installed Operators* page in the OpenShift Container Platform web console,
181+
+
182+
.hypershift-operators
183+
image::/images/hypershift/hypershift-ops.png[hypershift-operators,title="Hosted control plane Operators"]
184+
185+
. Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu.
186+
+
187+
.hypershif-operators-applications
188+
image::/images/hypershift/hypershift-ops-applications.png[hypershift-ops-applications,title="AHosted control plane applications"]
189+
190+
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.
191+
192+
For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault].
193+
194+
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].
195+
196+
=== Automating the deployment of a hosted control plane nodes
197+
198+
.Prerequisites
199+
* A management cluster.
200+
* The `hypershift` CLI installed. For instructions, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/hosted_control_planes/preparing-to-deploy-hosted-control-planes#hcp-cli-terminal_hcp-cli[Installing the hosted control planes command-line interface from the tereminal].
201+
* 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].
202+
* Ansible is installed on your system, with `kuberenetes.core collections`
203+
* Pull secret obtained from link:https://console.redhat.chttps://console.redhat.com/openshift/install/aws/installer-provisioned[Install OpenShift on AWS with installer-provisioned infrastructure] and converted to json format.
204+
* AWS credentials with permissions to create IAM roles and policies.
205+
206+
.Procedure
207+
208+
. Fork the link:https://github.com/validatedpatterns/hypershift-automation[hypershift-automation] repository on GitHub.
209+
210+
. Clone the forked copy of this repository.
211+
+
212+
[source,terminal]
213+
----
214+
$ git clone [email protected]:validatedpatterns/hypershift-automation.git
215+
----
216+
217+
. Go to your repository: Ensure you are in the root directory of your Git repository by using:
218+
+
219+
[source,terminal]
220+
----
221+
$ cd /path/to/your/repository
222+
----
223+
224+
. Edit the `vars.yml` file:
225+
+
226+
[source,terminal]
227+
----
228+
vi vars.yml
229+
----
230+
+
231+
.Example
232+
[source,terminal]
233+
----
234+
#Actions -e create=true "creates a cluster" -e destroy=true "destroys a cluster"
235+
create: true
236+
destroy: false
237+
238+
#Create IAM
239+
create_iam: false
240+
241+
#Cluster Info - We use these to create/destroy clusters
242+
name: democluster
243+
domain: aws.validatedpatterns.io
244+
region: us-east-1
245+
246+
#Cluster Characteristics - Describe how you want the cluster deployed
247+
replicas: 1
248+
instance_type: m5.xlarge
249+
#Setting to default uses the hosting-clusters version for the release-image. To deploy with a specific
250+
#version, define it below: x.y.z (4.15.29)
251+
image: 4.17.0
252+
----
253+
254+
. Run the following command to create the hosted control plane:
255+
+
256+
[source,terminal]
257+
----
258+
$ make build
259+
----
260+
+
261+
This will take some time to create the hosted control plane and nodepool configuration.
262+
263+
. In the OpenShift container platform web console select *All Clusters* to display the *Cluster list*. A screen similar to the following is displayed:
264+
+
265+
.hypershift-cluster-list
266+
image::/images/hypershift/hypershift-cluster-list.png[hypershift-cluster-list,title="Hosted control plane cluster list"]
267+
268+
. Select for example the *democluster* to display the *Cluster details* page. A screen similar to the following is displayed:
269+
+
270+
.hypershift-cluster-details
271+
image::/images/hypershift/hypershift-cluster-details.png[hypershift-cluster-details,title="Hosted control plane cluster details"]
272+
273+
. Click *Download kubeconfig* to download the `kubeconfig` file for the hosted control plane.
274+
275+
.Verification
276+
277+
. Export the management cluster kubeconfig:
278+
+
279+
[source,terminal]
280+
----
281+
$ export MGMT_KUBECONFIG=</path/to/management-cluster-kubeconfig>
282+
----
283+
284+
. Run this command to find the `node-pool-name` for your cluster:
285+
+
286+
[source,terminal]
287+
----
288+
$ oc --kubeconfig="$MGMT_KUBECONFIG" get np -A
289+
----
290+
+
291+
.Example output
292+
[source,terminal]
293+
----
294+
NAMESPACE NAME CLUSTER DESIRED NODES CURRENT NODES AUTOSCALING AUTOREPAIR VERSION UPDATINGVERSION UPDATINGCONFIG MESSAGE
295+
clusters democluster-us-east-1a democluster 1 1 False False 4.17.0 False False
296+
----
297+
298+
. Run this command to export the downloaded `kubeconfig` file for your hosted control plane:
299+
+
300+
[source,terminal]
301+
----
302+
$ export HCP_KUBECONFIG=</path/to/hypershift-cluster-kubeconfig>
303+
----
304+
305+
. Use the `kubeconfig` file to view the cluster Operators of the hosted cluster. Enter the following command:
306+
+
307+
[source,terminal]
308+
----
309+
$ oc --kubeconfig="$HCP_KUBECONFIG" get co
310+
----
311+
+
312+
.Example output
313+
[source,terminal]
314+
----
315+
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE
316+
console 4.17.0 True False False 57m
317+
csi-snapshot-controller 4.17.0 True False False 66m
318+
dns 4.17.0 True False False 57m
319+
image-registry 4.17.0 True False False 57m
320+
ingress 4.17.0 True False False 57m
321+
insights 4.17.0 True False False 58m
322+
kube-apiserver 4.17.0 True False False 66m
323+
kube-controller-manager 4.17.0 True False False 66m
324+
kube-scheduler 4.17.0 True False False 66m
325+
kube-storage-version-migrator 4.17.0 True False False 58m
326+
monitoring 4.17.0 True False False 55m
327+
network 4.17.0 True False False 65m
328+
node-tuning 4.17.0 True False False 60m
329+
openshift-apiserver 4.17.0 True False False 66m
330+
openshift-controller-manager 4.17.0 True False False 66m
331+
openshift-samples 4.17.0 True False False 57m
332+
operator-lifecycle-manager 4.17.0 True False False 66m
333+
operator-lifecycle-manager-catalog 4.17.0 True False False 65m
334+
operator-lifecycle-manager-packageserver 4.17.0 True False False 66m
335+
service-ca 4.17.0 True False False 58m
336+
storage 4.17.0 True False False 60m
337+
----
338+
339+
. View the running pods on your hosted cluster by entering the following command:
340+
+
341+
[source,terminal]
342+
----
343+
$ oc --kubeconfig="$HCP_KUBECONFIG" get pods -A
344+
----
345+
+
346+
.Example output
347+
[source,terminal]
348+
----
349+
NAMESPACE NAME READY STATUS RESTARTS AGE
350+
kube-system konnectivity-agent-56gh5 1/1 Running 0 66m
351+
kube-system kube-apiserver-proxy-ip-10-0-129-28.ec2.internal 1/1 Running 0 66m
352+
open-cluster-management-agent-addon cluster-proxy-proxy-agent-7c7666c8f8-9d2xb 3/3 Running 0 64m
353+
open-cluster-management-agent-addon klusterlet-addon-workmgr-56c67649b6-8flx7 1/1 Running 0 64m
354+
open-cluster-management-agent-addon managed-serviceaccount-addon-agent-56d8f7c4bd-krtwt 1/1 Running 0 64m
355+
openshift-cluster-csi-drivers aws-ebs-csi-driver-node-tvgt9 3/3 Running 0 66m
356+
openshift-cluster-node-tuning-operator tuned-kmlsm 1/1 Running 0 66m
357+
openshift-cluster-samples-operator cluster-samples-operator-6895b9d4c7-nsm54 2/2 Running 0 64m
358+
openshift-console-operator console-operator-67d5f87dcc-hdv5j 1/1 Running 2 (64m ago) 64m
359+
openshift-console console-fcb9d74fc-5jkfx 1/1 Running 0 61m
360+
openshift-console downloads-57848c99-8t8xn 1/1 Running 0 64m
361+
openshift-dns dns-default-n62b6 2/2 Running 0 65m
362+
openshift-dns node-resolver-25vsw 1/1 Running 0 66m
363+
openshift-image-registry image-registry-5778996bc4-v4dw6 1/1 Running 1 (63m ago) 64m
364+
openshift-image-registry node-ca-qf4fv 1/1 Running 0 66m
365+
openshift-ingress-canary ingress-canary-rlz5k 1/1 Running 0 65m
366+
openshift-ingress router-default-7fc88ff765-88zt6 1/1 Running 0 64m
367+
openshift-insights insights-operator-567c5dd9fc-vhkr5 1/1 Running 1 (63m ago) 64m
368+
openshift-kube-storage-version-migrator-operator kube-storage-version-migrator-operator-5d64f77d9f-tbrmm 1/1 Running 1 (63m ago) 64m
369+
openshift-kube-storage-version-migrator migrator-76b9bc6b54-mjwwn 1/1 Running 0 64m
370+
openshift-machine-config-operator kube-rbac-proxy-crio-ip-10-0-129-28.ec2.internal 1/1 Running 0 66m
371+
openshift-monitoring alertmanager-main-0 6/6 Running 0 62m
372+
openshift-monitoring cluster-monitoring-operator-6589b986c8-bjb2t 1/1 Running 0 64m
373+
openshift-monitoring kube-state-metrics-575c55f885-xcwvp 3/3 Running 0 63m
374+
openshift-monitoring metrics-server-766fb8749c-qmbkp 1/1 Running 0 63m
375+
openshift-monitoring monitoring-plugin-5567ddf44-vgrwx 1/1 Running 0 63m
376+
openshift-monitoring node-exporter-gh76w 2/2 Running 0 63m
377+
openshift-monitoring openshift-state-metrics-7466fd7977-hqmwv 3/3 Running 0 63m
378+
openshift-monitoring prometheus-k8s-0 6/6 Running 0 62m
379+
openshift-monitoring prometheus-operator-5cf88995b6-sqqfq 2/2 Running 0 64m
380+
openshift-monitoring prometheus-operator-admission-webhook-7d744487ff-8xb7b 1/1 Running 0 64m
381+
openshift-monitoring telemeter-client-857df5b745-9v579 3/3 Running 0 62m
382+
openshift-monitoring thanos-querier-585746b745-thnfc 6/6 Running 0 63m
383+
openshift-multus multus-additional-cni-plugins-njkgb 1/1 Running 0 66m
384+
openshift-multus multus-k6ggs 1/1 Running 0 66m
385+
openshift-multus network-metrics-daemon-45wq7 2/2 Running 0 66m
386+
openshift-network-console networking-console-plugin-78b59bd487-ms4c7 1/1 Running 0 64m
387+
openshift-network-diagnostics network-check-source-7fbf9dfccb-ddvld 1/1 Running 0 64m
388+
openshift-network-diagnostics network-check-target-vvktk 1/1 Running 0 66m
389+
openshift-network-operator iptables-alerter-5s96x 1/1 Running 0 65m
390+
openshift-ovn-kubernetes ovnkube-node-9rsw4 8/8 Running 0 66m
391+
openshift-service-ca-operator service-ca-operator-7b9f58bd4b-b62m6 1/1 Running 1 (63m ago) 64m
392+
openshift-service-ca service-ca-554d4b766c-82h22 1/1 Running 0 64m
393+
----

Diff for: ‎static/images/hypershift/hypershift-cluster-details.png

44.8 KB
Loading

Diff for: ‎static/images/hypershift/hypershift-cluster-list.png

104 KB
Loading

Diff for: ‎static/images/hypershift/hypershift-ops-applications.png

152 KB
Loading

Diff for: ‎static/images/hypershift/hypershift-ops.png

139 KB
Loading

0 commit comments

Comments
 (0)