Chapter 4. Deploying hosted control planes

1. Create an Amazon Web Services (AWS) credential secret for the HyperShift Operator and name it hypershift-operator-external-dns-credentials in the local-cluster namespace.

2. See the following table to verify that the secret has the required fields:

   Expand

   Table 4.3. Required fields for the AWS secret

   Field name	Description	Optional or required
   provider	The DNS provider that manages the service-level DNS zone.	Required
   domain-filter	The service-level domain.	Required
   credentials	The credential file that supports all external DNS types.	Optional when you use AWS keys
   aws-access-key-id	The credential access key id.	Optional when you use the AWS DNS service
   aws-secret-access-key	The credential access key secret.	Optional when you use the AWS DNS service

   Show more

3. To create an AWS secret, run the following command:

   $ oc create secret generic <secret_name> \
     --from-literal=provider=aws \
     --from-literal=domain-filter=<domain_name> \
     --from-file=credentials=<path_to_aws_credentials_file> -n local-cluster

   Copy to Clipboard Toggle word wrap
   Note

   Disaster recovery backup for the secret is not automatically enabled. To back up the secret for disaster recovery, add the hypershift-operator-external-dns-credentials by entering the following command:

   $ oc label secret hypershift-operator-external-dns-credentials \
     -n local-cluster \
     cluster.open-cluster-management.io/backup=""

   Copy to Clipboard Toggle word wrap

Procedure

1. In the Route 53 management console, click Create hosted zone.
2. On the Hosted zone configuration page, type a domain name, verify that Public hosted zone is selected as the type, and click Create hosted zone.
3. After the zone is created, on the Records tab, note the values in the Value/Route traffic to column.
4. In the main domain, create an NS record to redirect the DNS requests to the delegated zone. In the Value field, enter the values that you noted in the previous step.
5. Click Create records.

6. Verify that the DNS hosted zone is working by creating a test entry in the new subzone and testing it with a dig command, such as in the following example:

   $ dig +short test.user-dest-public.aws.kerberos.com

   Copy to Clipboard Toggle word wrap

   Example output

   192.168.1.1

   Copy to Clipboard Toggle word wrap

7. To create a hosted cluster that sets the hostname for the LoadBalancer and Route services, enter the following command:

   $ hcp create cluster aws --name=<hosted_cluster_name> \
     --endpoint-access=PublicAndPrivate \
     --external-dns-domain=<public_hosted_zone> ... 

   1

   Copy to Clipboard Toggle word wrap

   1

   Replace <public_hosted_zone> with the public hosted zone that you created.

   Example services block for the hosted cluster

     platform:
       aws:
         endpointAccess: PublicAndPrivate
   ...
     services:
     - service: APIServer
       servicePublishingStrategy:
         route:
           hostname: api-example.service-provider-domain.com
         type: Route
     - service: OAuthServer
       servicePublishingStrategy:
         route:
           hostname: oauth-example.service-provider-domain.com
         type: Route
     - service: Konnectivity
       servicePublishingStrategy:
         type: Route
     - service: Ignition
       servicePublishingStrategy:
         type: Route

   Copy to Clipboard Toggle word wrap

Procedure

1. To access your management cluster, enter the following command:

   $ export KUBECONFIG=<path_to_management_cluster_kubeconfig>

   Copy to Clipboard Toggle word wrap

2. Verify that the External DNS Operator is running by entering the following command:

   $ oc get pod -n hypershift -lapp=external-dns

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                            READY   STATUS    RESTARTS   AGE
   external-dns-7c89788c69-rn8gp   1/1     Running   0          40s

   Copy to Clipboard Toggle word wrap

3. To create a hosted cluster by using external DNS, enter the following command:

   $ hcp create cluster aws \
       --role-arn <arn_role> \ 

   1

   
       --instance-type <instance_type> \ 

   2

   
       --region <region> \ 

   3

   
       --auto-repair \
       --generate-ssh \
       --name <hosted_cluster_name> \ 

   4

   
       --namespace clusters \
       --base-domain <service_consumer_domain> \ 

   5

   
       --node-pool-replicas <node_replica_count> \ 

   6

   
       --pull-secret <path_to_your_pull_secret> \ 

   7

   
       --release-image quay.io/openshift-release-dev/ocp-release:<ocp_release_image> \ 

   8

   
       --external-dns-domain=<service_provider_domain> \ 

   9

   
       --endpoint-access=PublicAndPrivate 

   10

   
       --sts-creds <path_to_sts_credential_file> 

   11

   Copy to Clipboard Toggle word wrap

   1

   Specify the Amazon Resource Name (ARN), for example, arn:aws:iam::820196288204:role/myrole.

   2

   Specify the instance type, for example, m6i.xlarge.

   3

   Specify the AWS region, for example, us-east-1.

   4

   Specify your hosted cluster name, for example, my-external-aws.

   5

   Specify the public hosted zone that the service consumer owns, for example, service-consumer-domain.com.

   6

   Specify the node replica count, for example, 2.

   7

   Specify the path to your pull secret file.

   8

   Specify the supported OpenShift Container Platform version that you want to use, for example, 4.17.0-multi.

   9

   Specify the public hosted zone that the service provider owns, for example, service-provider-domain.com.

   10

   Set as PublicAndPrivate. You can use external DNS with Public or PublicAndPrivate configurations only.

   11

   Specify the path to your AWS STS credentials file, for example, /home/user/sts-creds/sts-creds.json.

Procedure

1. Generate the kubeconfig file by entering the following command:

   $ hcp create kubeconfig --namespace <hosted_cluster_namespace> \
     --name <hosted_cluster_name> > <hosted_cluster_name>.kubeconfig

   Copy to Clipboard Toggle word wrap

2. After you save the kubeconfig file, access the hosted cluster by entering the following command:

   $ oc --kubeconfig <hosted_cluster_name>.kubeconfig get nodes

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a namespace to store your hardware inventory by entering the following command:

   $ oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig create \
     namespace <namespace_example>

   Copy to Clipboard Toggle word wrap

   where:

   <directory_example>

   Is the name of the directory where the kubeconfig file for the management cluster is saved.

   <namespace_example>

   Is the name of the namespace that you are creating; for example, hardware-inventory.

   Example output

   namespace/hardware-inventory created

   Copy to Clipboard Toggle word wrap

2. Copy the pull secret of the management cluster by entering the following command:

   $ oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig \
     -n openshift-config get secret pull-secret -o yaml \
     | grep -vE "uid|resourceVersion|creationTimestamp|namespace" \
     | sed "s/openshift-config/<namespace_example>/g" \
     | oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig \
     -n <namespace> apply -f -

   Copy to Clipboard Toggle word wrap

   where:

   <directory_example>

   Is the name of the directory where the kubeconfig file for the management cluster is saved.

   <namespace_example>

   Is the name of the namespace that you are creating; for example, hardware-inventory.

   Example output

   secret/pull-secret created

   Copy to Clipboard Toggle word wrap

3. Create the InfraEnv resource by adding the following content to a YAML file:

   apiVersion: agent-install.openshift.io/v1beta1
   kind: InfraEnv
   metadata:
     name: hosted
     namespace: <namespace_example>
   spec:
     additionalNTPSources:
     - <ip_address>
     pullSecretRef:
       name: pull-secret
     sshAuthorizedKey: <ssh_public_key>
   # ...

   Copy to Clipboard Toggle word wrap

4. Apply the changes to the YAML file by entering the following command:

   $ oc apply -f <infraenv_config>.yaml

   Copy to Clipboard Toggle word wrap

   Replace <infraenv_config> with the name of your file.

5. Verify that the InfraEnv resource was created by entering the following command:

   $ oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig \
     -n <namespace_example> get infraenv hosted

   Copy to Clipboard Toggle word wrap

6. Add bare-metal hosts by following one of two methods:

   • If you do not use the Metal3 Operator, obtain the discovery ISO from the InfraEnv resource and boot the hosts manually by completing the following steps:

     1. Download the live ISO by entering the following commands:

        $ oc get infraenv -A

        Copy to Clipboard Toggle word wrap

        $ oc get infraenv <namespace_example> -o jsonpath='{.status.isoDownloadURL}' -n <namespace_example> <iso_url>

        Copy to Clipboard Toggle word wrap
     2. Boot the ISO. The node communicates with the Assisted Service and registers as an agent in the same namespace as the InfraEnv resource.

     3. For each agent, set the installation disk ID and hostname, and approve it to indicate that the agent is ready for use. Enter the following commands:

        $ oc -n <hosted_control_plane_namespace> get agents

        Copy to Clipboard Toggle word wrap

        Example output

        NAME                                   CLUSTER   APPROVED   ROLE          STAGE
        86f7ac75-4fc4-4b36-8130-40fa12602218                        auto-assign
        e57a637f-745b-496e-971d-1abbf03341ba                        auto-assign

        Copy to Clipboard Toggle word wrap

        $ oc -n <hosted_control_plane_namespace> \
          patch agent 86f7ac75-4fc4-4b36-8130-40fa12602218 \
          -p '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-0.example.krnl.es"}}' \
          --type merge

        Copy to Clipboard Toggle word wrap

        $ oc -n <hosted_control_plane_namespace> \
          patch agent 23d0c614-2caa-43f5-b7d3-0b3564688baa -p \
          '{"spec":{"installation_disk_id":"/dev/sda","approved":true,"hostname":"worker-1.example.krnl.es"}}' \
          --type merge

        Copy to Clipboard Toggle word wrap

        $ oc -n <hosted_control_plane_namespace> get agents

        Copy to Clipboard Toggle word wrap

        Example output

        NAME                                   CLUSTER   APPROVED   ROLE          STAGE
        86f7ac75-4fc4-4b36-8130-40fa12602218             true       auto-assign
        e57a637f-745b-496e-971d-1abbf03341ba             true       auto-assign

        Copy to Clipboard Toggle word wrap

   • If you use the Metal3 Operator, you can automate the bare-metal host registration by creating the following objects:

     1. Create a YAML file and add the following content to it:

        apiVersion: v1
        kind: Secret
        metadata:
          name: hosted-worker0-bmc-secret
          namespace: <namespace_example>
        data:
          password: <password>
          username: <username>
        type: Opaque
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: hosted-worker1-bmc-secret
          namespace: <namespace_example>
        data:
          password: <password>
          username: <username>
        type: Opaque
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: hosted-worker2-bmc-secret
          namespace: <namespace_example>
        data:
          password: <password>
          username: <username>
        type: Opaque
        ---
        apiVersion: metal3.io/v1alpha1
        kind: BareMetalHost
        metadata:
          name: hosted-worker0
          namespace: <namespace_example>
          labels:
            infraenvs.agent-install.openshift.io: hosted
          annotations:
            inspect.metal3.io: disabled
            bmac.agent-install.openshift.io/hostname: hosted-worker0
        spec:
          automatedCleaningMode: disabled
          bmc:
            disableCertificateVerification: True
            address: <bmc_address>
            credentialsName: hosted-worker0-bmc-secret
          bootMACAddress: aa:aa:aa:aa:02:01
          online: true
        ---
        apiVersion: metal3.io/v1alpha1
        kind: BareMetalHost
        metadata:
          name: hosted-worker1
          namespace: <namespace_example>
          labels:
            infraenvs.agent-install.openshift.io: hosted
          annotations:
            inspect.metal3.io: disabled
            bmac.agent-install.openshift.io/hostname: hosted-worker1
        spec:
          automatedCleaningMode: disabled
          bmc:
            disableCertificateVerification: True
            address: <bmc_address>
            credentialsName: hosted-worker1-bmc-secret
          bootMACAddress: aa:aa:aa:aa:02:02
          online: true
        ---
        apiVersion: metal3.io/v1alpha1
        kind: BareMetalHost
        metadata:
          name: hosted-worker2
          namespace: <namespace_example>
          labels:
            infraenvs.agent-install.openshift.io: hosted
          annotations:
            inspect.metal3.io: disabled
            bmac.agent-install.openshift.io/hostname: hosted-worker2
        spec:
          automatedCleaningMode: disabled
          bmc:
            disableCertificateVerification: True
            address: <bmc_address>
            credentialsName: hosted-worker2-bmc-secret
          bootMACAddress: aa:aa:aa:aa:02:03
          online: true
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: capi-provider-role
          namespace: <namespace_example>
        rules:
        - apiGroups:
          - agent-install.openshift.io
          resources:
          - agents
          verbs:
          - '*'

        Copy to Clipboard Toggle word wrap

        where:

        <namespace_example>

        Is the your namespace.

        <password>

        Is the password for your secret.

        <username>

        Is the user name for your secret.

        <bmc_address>

        Is the BMC address for the BareMetalHost object.

        Note

        When you apply this YAML file, the following objects are created:

        • Secrets with credentials for the Baseboard Management Controller (BMCs)
        • The BareMetalHost objects
        • A role for the HyperShift Operator to be able to manage the agents

        Notice how the InfraEnv resource is referenced in the BareMetalHost objects by using the infraenvs.agent-install.openshift.io: hosted custom label. This ensures that the nodes are booted with the ISO generated.

     2. Apply the changes to the YAML file by entering the following command:

        $ oc apply -f <bare_metal_host_config>.yaml

        Copy to Clipboard Toggle word wrap

        Replace <bare_metal_host_config> with the name of your file.

7. Enter the following command, and then wait a few minutes for the BareMetalHost objects to move to the Provisioning state:

   $ oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig -n <namespace_example> get bmh

   Copy to Clipboard Toggle word wrap

   Example output

   NAME             STATE          CONSUMER   ONLINE   ERROR   AGE
   hosted-worker0   provisioning              true             106s
   hosted-worker1   provisioning              true             106s
   hosted-worker2   provisioning              true             106s

   Copy to Clipboard Toggle word wrap

8. Enter the following command to verify that nodes are booting and showing up as agents. This process can take a few minutes, and you might need to enter the command more than once.

   $ oc --kubeconfig ~/<directory_example>/mgmt-kubeconfig -n <namespace_example> get agent

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                                   CLUSTER   APPROVED   ROLE          STAGE
   aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0201             true       auto-assign
   aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0202             true       auto-assign
   aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaa0203             true       auto-assign

   Copy to Clipboard Toggle word wrap

Procedure

1. Open the OpenShift Container Platform web console and log in by entering your administrator credentials. For instructions to open the console, see "Accessing the web console".
2. In the console header, ensure that All Clusters is selected.
3. Click Infrastructure Host inventory Create infrastructure environment.
4. After you create the InfraEnv resource, add bare-metal hosts from within the InfraEnv view by clicking Add hosts and selecting from the available options.

Procedure

1. Create a namespace by entering the following command:

   $ oc create ns <hosted_cluster_namespace>

   Copy to Clipboard Toggle word wrap

   Replace <hosted_cluster_namespace> with an identifier for your hosted cluster namespace. The HyperShift Operator creates the namespace. During the hosted cluster creation process on bare-metal infrastructure, a generated Cluster API provider role requires that the namespace already exists.

2. Create the configuration file for your hosted cluster by entering the following command:

   $ hcp create cluster agent \
     --name=<hosted_cluster_name> \

   1

   
     --pull-secret=<path_to_pull_secret> \

   2

   
     --agent-namespace=<hosted_control_plane_namespace> \

   3

   
     --base-domain=<base_domain> \

   4

   
     --api-server-address=api.<hosted_cluster_name>.<base_domain> \

   5

   
     --etcd-storage-class=<etcd_storage_class> \

   6

   
     --ssh-key=<path_to_ssh_key> \

   7

   
     --namespace=<hosted_cluster_namespace> \

   8

   
     --control-plane-availability-policy=HighlyAvailable \

   9

   
     --release-image=quay.io/openshift-release-dev/ocp-release:<ocp_release_image>-multi \

   10

   
     --node-pool-replicas=<node_pool_replica_count> \

   11

   
     --render \
     --render-sensitive \
     --ssh-key <home_directory>/<path_to_ssh_key>/<ssh_key> > hosted-cluster-config.yaml 

   12

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of your hosted cluster, such as example.

   2

   Specify the path to your pull secret, such as /user/name/pullsecret.

   3

   Specify your hosted control plane namespace, such as clusters-example. Ensure that agents are available in this namespace by using the oc get agent -n <hosted_control_plane_namespace> command.

   4

   Specify your base domain, such as krnl.es.

   5

   The --api-server-address flag defines the IP address that gets used for the Kubernetes API communication in the hosted cluster. If you do not set the --api-server-address flag, you must log in to connect to the management cluster.

   6

   Specify the etcd storage class name, such as lvm-storageclass.

   7

   Specify the path to your SSH public key. The default file path is ~/.ssh/id_rsa.pub.

   8

   Specify your hosted cluster namespace.

   9

   Specify the availability policy for the hosted control plane components. Supported options are SingleReplica and HighlyAvailable. The default value is HighlyAvailable.

   10

   Specify the supported OpenShift Container Platform version that you want to use, such as 4.19.0-multi. If you are using a disconnected environment, replace <ocp_release_image> with the digest image. To extract the OpenShift Container Platform release image digest, see Extracting the OpenShift Container Platform release image digest.

   11

   Specify the node pool replica count, such as 3. You must specify the replica count as 0 or greater to create the same number of replicas. Otherwise, you do not create node pools.

   12

   After the --ssh-key flag, specify the path to the SSH key, such as user/.ssh/id_rsa.

3. Configure the service publishing strategy. By default, hosted clusters use the NodePort service publishing strategy because node ports are always available without additional infrastructure. However, you can configure the service publishing strategy to use a load balancer.

   • If you are using the default NodePort strategy, configure the DNS to point to the hosted cluster compute nodes, not the management cluster nodes. For more information, see "DNS configurations on bare metal".

   • For production environments, use the LoadBalancer strategy because this strategy provides certificate handling and automatic DNS resolution. The following example demonstrates changing the service publishing LoadBalancer strategy in your hosted cluster configuration file:

     # ...
     spec:
       services:
       - service: APIServer
         servicePublishingStrategy:
           type: LoadBalancer 

     1

     
       - service: Ignition
         servicePublishingStrategy:
           type: Route
       - service: Konnectivity
         servicePublishingStrategy:
           type: Route
       - service: OAuthServer
         servicePublishingStrategy:
           type: Route
       - service: OIDC
         servicePublishingStrategy:
           type: Route
       sshKey:
         name: <ssh_key>
     # ...

     Copy to Clipboard Toggle word wrap

     1

     Specify LoadBalancer as the API Server type. For all other services, specify Route as the type.

4. Apply the changes to the hosted cluster configuration file by entering the following command:

   $ oc apply -f hosted_cluster_config.yaml

   Copy to Clipboard Toggle word wrap

5. Check for the creation of the hosted cluster, node pools, and pods by entering the following commands:

   $ oc get hostedcluster \
     <hosted_cluster_namespace> -n \
     <hosted_cluster_namespace> -o \
     jsonpath='{.status.conditions[?(@.status=="False")]}' | jq .

   Copy to Clipboard Toggle word wrap

   $ oc get nodepool \
     <hosted_cluster_namespace> -n \
     <hosted_cluster_namespace> -o \
     jsonpath='{.status.conditions[?(@.status=="False")]}' | jq .

   Copy to Clipboard Toggle word wrap

   $ oc get pods -n <hosted_cluster_namespace>

   Copy to Clipboard Toggle word wrap
6. Confirm that the hosted cluster is ready. The status of Available: True indicates the readiness of the cluster and the node pool status shows AllMachinesReady: True. These statuses indicate the healthiness of all cluster Operators.

7. Install MetalLB in the hosted cluster:

   1. Extract the kubeconfig file from the hosted cluster and set the environment variable for hosted cluster access by entering the following commands:

      $ oc get secret \
        <hosted_cluster_namespace>-admin-kubeconfig \
        -n <hosted_cluster_namespace> \
        -o jsonpath='{.data.kubeconfig}' \
        | base64 -d > \
        kubeconfig-<hosted_cluster_namespace>.yaml

      Copy to Clipboard Toggle word wrap

      $ export KUBECONFIG="/path/to/kubeconfig-<hosted_cluster_namespace>.yaml"

      Copy to Clipboard Toggle word wrap

   2. Install the MetalLB Operator by creating the install-metallb-operator.yaml file:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: metallb-system
      ---
      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: metallb-operator
        namespace: metallb-system
      ---
      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: metallb-operator
        namespace: metallb-system
      spec:
        channel: "stable"
        name: metallb-operator
        source: redhat-operators
        sourceNamespace: openshift-marketplace
        installPlanApproval: Automatic
      # ...

      Copy to Clipboard Toggle word wrap

   3. Apply the file by entering the following command:

      $ oc apply -f install-metallb-operator.yaml

      Copy to Clipboard Toggle word wrap

   4. Configure the MetalLB IP address pool by creating the deploy-metallb-ipaddresspool.yaml file:

      apiVersion: metallb.io/v1beta1
      kind: IPAddressPool
      metadata:
        name: metallb
        namespace: metallb-system
      spec:
        autoAssign: true
        addresses:
        - 10.11.176.71-10.11.176.75
      ---
      apiVersion: metallb.io/v1beta1
      kind: L2Advertisement
      metadata:
        name: l2advertisement
        namespace: metallb-system
      spec:
        ipAddressPools:
        - metallb
      # ...

      Copy to Clipboard Toggle word wrap

   5. Apply the configuration by entering the following command:

      $ oc apply -f deploy-metallb-ipaddresspool.yaml

      Copy to Clipboard Toggle word wrap

   6. Verify the installation of MetalLB by checking the Operator status, the IP address pool, and the L2Advertisement resource by entering the following commands:

      $ oc get pods -n metallb-system

      Copy to Clipboard Toggle word wrap

      $ oc get ipaddresspool -n metallb-system

      Copy to Clipboard Toggle word wrap

      $ oc get l2advertisement -n metallb-system

      Copy to Clipboard Toggle word wrap

8. Configure the load balancer for ingress:

   1. Create the ingress-loadbalancer.yaml file:

      apiVersion: v1
      kind: Service
      metadata:
        annotations:
          metallb.universe.tf/address-pool: metallb
        name: metallb-ingress
        namespace: openshift-ingress
      spec:
        ports:
          - name: http
            protocol: TCP
            port: 80
            targetPort: 80
          - name: https
            protocol: TCP
            port: 443
            targetPort: 443
        selector:
          ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default
        type: LoadBalancer
      # ...

      Copy to Clipboard Toggle word wrap

   2. Apply the configuration by entering the following command:

      $ oc apply -f ingress-loadbalancer.yaml

      Copy to Clipboard Toggle word wrap

   3. Verify that the load balancer service works as expected by entering the following command:

      $ oc get svc metallb-ingress -n openshift-ingress

      Copy to Clipboard Toggle word wrap

      Example output

      NAME              TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)                      AGE
      metallb-ingress   LoadBalancer   172.31.127.129   10.11.176.71   80:30961/TCP,443:32090/TCP   16h

      Copy to Clipboard Toggle word wrap

9. Configure the DNS to work with the load balancer:

   1. Configure the DNS for the apps domain by pointing the *.apps.<hosted_cluster_namespace>.<base_domain> wildcard DNS record to the load balancer IP address.

   2. Verify the DNS resolution by entering the following command:

      $ nslookup console-openshift-console.apps.<hosted_cluster_namespace>.<base_domain> <load_balancer_ip_address>

      Copy to Clipboard Toggle word wrap

      Example output

      Server:         10.11.176.1
      Address:        10.11.176.1#53
      
      Name:   console-openshift-console.apps.my-hosted-cluster.sample-base-domain.com
      Address: 10.11.176.71

      Copy to Clipboard Toggle word wrap

Verification

1. Check the cluster Operators by entering the following command:

   $ oc get clusteroperators

   Copy to Clipboard Toggle word wrap

   Ensure that all Operators show AVAILABLE: True, PROGRESSING: False, and DEGRADED: False.

2. Check the nodes by entering the following command:

   $ oc get nodes

   Copy to Clipboard Toggle word wrap

   Ensure that each node has the READY status.

3. Test access to the console by entering the following URL in a web browser:

   https://console-openshift-console.apps.<hosted_cluster_namespace>.<base_domain>

   Copy to Clipboard Toggle word wrap

Procedure

1. Open the OpenShift Container Platform web console and log in by entering your administrator credentials. For instructions to open the console, see "Accessing the web console".
2. In the console header, ensure that All Clusters is selected.
3. Click Infrastructure Clusters.

4. Click Create cluster Host inventory Hosted control plane.

   The Create cluster page is displayed.

5. On the Create cluster page, follow the prompts to enter details about the cluster, node pools, networking, and automation.

   Note

   As you enter details about the cluster, you might find the following tips useful:

   • If you want to use predefined values to automatically populate fields in the console, you can create a host inventory credential. For more information, see "Creating a credential for an on-premises environment".
   • On the Cluster details page, the pull secret is your OpenShift Container Platform pull secret that you use to access OpenShift Container Platform resources. If you selected a host inventory credential, the pull secret is automatically populated.
   • On the Node pools page, the namespace contains the hosts for the node pool. If you created a host inventory by using the console, the console creates a dedicated namespace.
   • On the Networking page, you select an API server publishing strategy. The API server for the hosted cluster can be exposed either by using an existing load balancer or as a service of the NodePort type. A DNS entry must exist for the api.<hosted_cluster_name>.<base_domain> setting that points to the destination where the API server can be reached. This entry can be a record that points to one of the nodes in the management cluster or a record that points to a load balancer that redirects incoming traffic to the Ingress pods.

6. Review your entries and click Create.

   The Hosted cluster view is displayed.

7. Monitor the deployment of the hosted cluster in the Hosted cluster view.
8. If you do not see information about the hosted cluster, ensure that All Clusters is selected, then click the cluster name.
9. Wait until the control plane components are ready. This process can take a few minutes.
10. To view the node pool status, scroll to the NodePool section. The process to install the nodes takes about 10 minutes. You can also click Nodes to confirm whether the nodes joined the hosted cluster.

Procedure

1. Create a YAML file to define Image Content Source Policies (ICSP). See the following example:

   - mirrors:
     - brew.registry.redhat.io
     source: registry.redhat.io
   - mirrors:
     - brew.registry.redhat.io
     source: registry.stage.redhat.io
   - mirrors:
     - brew.registry.redhat.io
     source: registry-proxy.engineering.redhat.com

   Copy to Clipboard Toggle word wrap
2. Save the file as icsp.yaml. This file contains your mirror registries.

3. To create a hosted cluster by using your mirror registries, run the following command:

   $ hcp create cluster agent \
       --name=<hosted_cluster_name> \

   1

   
       --pull-secret=<path_to_pull_secret> \

   2

   
       --agent-namespace=<hosted_control_plane_namespace> \

   3

   
       --base-domain=<basedomain> \

   4

   
       --api-server-address=api.<hosted_cluster_name>.<basedomain> \

   5

   
       --image-content-sources icsp.yaml  \

   6

   
       --ssh-key  <path_to_ssh_key> \

   7

   
       --namespace <hosted_cluster_namespace> \

   8

   
       --release-image=quay.io/openshift-release-dev/ocp-release:<ocp_release_image> 

   9

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of your hosted cluster, for instance, example.

   2

   Specify the path to your pull secret, for example, /user/name/pullsecret.

   3

   Specify your hosted control plane namespace, for example, clusters-example. Ensure that agents are available in this namespace by using the oc get agent -n <hosted-control-plane-namespace> command.

   4

   Specify your base domain, for example, krnl.es.

   5

   The --api-server-address flag defines the IP address that is used for the Kubernetes API communication in the hosted cluster. If you do not set the --api-server-address flag, you must log in to connect to the management cluster.

   6

   Specify the icsp.yaml file that defines ICSP and your mirror registries.

   7

   Specify the path to your SSH public key. The default file path is ~/.ssh/id_rsa.pub.

   8

   Specify your hosted cluster namespace.

   9

   Specify the supported OpenShift Container Platform version that you want to use, for example, 4.17.0-multi. If you are using a disconnected environment, replace <ocp_release_image> with the digest image. To extract the OpenShift Container Platform release image digest, see "Extracting the OpenShift Container Platform release image digest".

Procedure

1. Create a hosted cluster with the KubeVirt platform by entering the following command:

   $ hcp create cluster kubevirt \
     --name <hosted_cluster_name> \

   1

   
     --node-pool-replicas <node_pool_replica_count> \

   2

   
     --pull-secret <path_to_pull_secret> \

   3

   
     --memory <value_for_memory> \

   4

   
     --cores <value_for_cpu> \

   5

   
     --etcd-storage-class=<etcd_storage_class> 

   6

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of your hosted cluster, for example, my-hosted-cluster.

   2

   Specify the node pool replica count, for example, 3. You must specify the replica count as 0 or greater to create the same number of replicas. Otherwise, no node pools are created.

   3

   Specify the path to your pull secret, for example, /user/name/pullsecret.

   4

   Specify a value for memory, for example, 6Gi.

   5

   Specify a value for CPU, for example, 2.

   6

   Specify the etcd storage class name, for example, lvm-storageclass.

   Note

   You can use the --release-image flag to set up the hosted cluster with a specific OpenShift Container Platform release.

   A default node pool is created for the cluster with two virtual machine worker replicas according to the --node-pool-replicas flag.

2. After a few moments, verify that the hosted control plane pods are running by entering the following command:

   $ oc -n clusters-<hosted-cluster-name> get pods

   Copy to Clipboard Toggle word wrap

   Example output

   NAME                                                  READY   STATUS    RESTARTS   AGE
   capi-provider-5cc7b74f47-n5gkr                        1/1     Running   0          3m
   catalog-operator-5f799567b7-fd6jw                     2/2     Running   0          69s
   certified-operators-catalog-784b9899f9-mrp6p          1/1     Running   0          66s
   cluster-api-6bbc867966-l4dwl                          1/1     Running   0          66s
   .
   .
   .
   redhat-operators-catalog-9d5fd4d44-z8qqk              1/1     Running   0          66s

   Copy to Clipboard Toggle word wrap

   A hosted cluster that has worker nodes that are backed by KubeVirt virtual machines typically takes 10-15 minutes to be fully provisioned.

Procedure

1. Open the OpenShift Container Platform web console and log in by entering your administrator credentials.
2. In the console header, ensure that All Clusters is selected.
3. Click Infrastructure > Clusters.
4. Click Create cluster > Red Hat OpenShift Virtualization > Hosted.

5. On the Create cluster page, follow the prompts to enter details about the cluster and node pools.

   Note
   • If you want to use predefined values to automatically populate fields in the console, you can create a OpenShift Virtualization credential. For more information, see Creating a credential for an on-premises environment.
   • On the Cluster details page, the pull secret is your OpenShift Container Platform pull secret that you use to access OpenShift Container Platform resources. If you selected a OpenShift Virtualization credential, the pull secret is automatically populated.

6. Review your entries and click Create.

   The Hosted cluster view is displayed.

Verification

1. Monitor the deployment of the hosted cluster in the Hosted cluster view. If you do not see information about the hosted cluster, ensure that All Clusters is selected, and click the cluster name.
2. Wait until the control plane components are ready. This process can take a few minutes.
3. To view the node pool status, scroll to the NodePool section. The process to install the nodes takes about 10 minutes. You can also click Nodes to confirm whether the nodes joined the hosted cluster.