--- title: About image-based deployments for managed single-node OpenShift --- # About image-based deployments for managed single-node OpenShift {#ibi-edge-image-based-install} When a host preinstalled with single-node OpenShift using an image-based installation arrives at a remote site, a technician can easily reconfigure and deploy the host in a matter of minutes. For clusters with a hub-and-spoke architecture, to complete the deployment of a preinstalled host, you must first define site-specific configuration resources on the hub cluster for each host. These resources contain configuration information such as the properties of the bare-metal host, authentication details, and other deployment and networking information. The Image Based Install (IBI) Operator creates a configuration ISO from these resources, and then boots the host with the configuration ISO attached. The host mounts the configuration ISO and runs the reconfiguration process. When the reconfiguration completes, the single-node OpenShift cluster is ready. > [!NOTE] > You must create distinct configuration resources for each bare-metal host. See the following high-level steps to deploy a preinstalled host in a cluster with a hub-and-spoke architecture: 1. Install the IBI Operator on the hub cluster. 2. Create site-specific configuration resources in the hub cluster for each host. 3. The IBI Operator creates a configuration ISO from these resources and boots the target host with the configuration ISO attached. 4. The host mounts the configuration ISO and runs the reconfiguration process. When the reconfiguration completes, the single-node OpenShift cluster is ready. > [!NOTE] > Alternatively, you can manually deploy a preinstalled host for a cluster without using a hub cluster. You must define an `ImageBasedConfig` resource and an installation manifest, and provide these as inputs to the `openshift-install` installation program. For more information, see "Deploying a single-node OpenShift cluster using the `openshift-install` program". **Additional resources** {._additional-resources} - [Deploying a single-node OpenShift cluster using the `openshift-install` program](/openshift-docs-markdown/edge_computing/image_base_install/ibi_deploying_sno_clusters/ibi-edge-image-based-install-standalone#create-standalone-config-iso_ibi-edge-image-based-install) ## Installing the Image Based Install Operator {#ibi-install-ibi-operator_ibi-edge-image-based-install} The Image Based Install (IBI) Operator is part of the image-based deployment workflow for preinstalled single-node OpenShift on bare-metal hosts. > [!NOTE] > The IBI Operator is part of the multicluster engine for Kubernetes Operator from MCE version 2.7. **Prerequisites** - You logged in as a user with `cluster-admin` privileges. - You deployed a Red Hat Advanced Cluster Management (RHACM) hub cluster or you deployed the multicluster engine for Kubernetes Operator. - You reviewed the required versions of software components in the section "Software prerequisites for an image-based installation". **Procedure** - Set the `enabled` specification to `true` for the `image-based-install-operator` component in the `MultiClusterEngine` resource by running the following command: ```terminal $ oc patch multiclusterengines.multicluster.openshift.io multiclusterengine --type json \ --patch '[{"op": "add", "path":"/spec/overrides/components/-", "value": {"name":"image-based-install-operator","enabled": true}}]' ``` **Verification** - Check that the Image Based Install Operator pod is running by running the following command: ```terminal $ oc get pods -A | grep image-based ``` Example output: ```terminal multicluster-engine image-based-install-operator-57fb8sc423-bxdj8 2/2 Running 0 5m ``` ## Deploying a managed single-node OpenShift cluster using the IBI Operator {#ibi-create-config-iso_ibi-edge-image-based-install} Create the site-specific configuration resources in the hub cluster to initiate the image-based deployment of a preinstalled host. When you create these configuration resources in the hub cluster, the Image Based Install (IBI) Operator generates a configuration ISO and attaches it to the target host to begin the site-specific configuration process. When the configuration process completes, the single-node OpenShift cluster is ready. > [!NOTE] > For more information about the configuration resources that you must configure in the hub cluster, see "Cluster configuration resources for deploying a preinstalled host". **Prerequisites** - You preinstalled a host with single-node OpenShift using an image-based installation. - You logged in as a user with `cluster-admin` privileges. - You deployed a Red Hat Advanced Cluster Management (RHACM) hub cluster or you deployed the multicluster engine for Kubernetes operator (MCE). - You installed the IBI Operator on the hub cluster. - You created a pull secret to authenticate pull requests. For more information, see "Using image pull secrets". **Procedure** 1. Create the `ibi-ns` namespace by running the following command: ```terminal $ oc create namespace ibi-ns ``` 2. Create the `Secret` resource for your image registry: 1. Create a YAML file that defines the `Secret` resource for your image registry: Example `secret-image-registry.yaml` file: ```yaml apiVersion: v1 kind: Secret metadata: name: ibi-image-pull-secret namespace: ibi-ns stringData: .dockerconfigjson: type: kubernetes.io/dockerconfigjson ``` where: `` : Specifies base64-encoded credential details. See the "Additional resources" section for more information about using image pull secrets. 2. Create the `Secret` resource for your image registry by running the following command: ```terminal $ oc create -f secret-image-registry.yaml ``` 3. Optional: Configure static networking for the host: 1. Create a `Secret` resource containing the static network configuration in `nmstate` format: Example `host-network-config-secret.yaml` file: ```yaml apiVersion: v1 kind: Secret metadata: name: namespace: ibi-ns type: Opaque stringData: nmstate: | interfaces: - name: type: ethernet state: up ipv4: enabled: true address: - ip: 192.168.200.25 prefix-length: 24 dhcp: false ipv6: enabled: false dns-resolver: config: server: - - 192.168.15.48 routes: config: - destination: 0.0.0.0/0 metric: 150 next-hop-address: 192.168.200.254 next-hop-interface: table-id: 254 ``` where: `` : Specifies the name for the `Secret` resource, for example `host-network-config-secret`. `nmstate` : Specifies the static network configuration in `nmstate` format. `` : Specifies the name of the interface on the host, for example `ens1f0`. The name of the interface must match the actual NIC name as shown in the operating system. To use your MAC address for NIC matching, set the `identifier` field to `mac-address`. `dhcp: false` : Specifies that DHCP is disabled to ensure `nmstate` assigns the static IP address to the interface. `` : Specifies one or more DNS servers that the system will use to resolve domain names, for example `192.168.15.47`. `config` : Specifies the default route through the `ens1f0` interface to the next hop IP address `192.168.200.254`. 4. Create the `BareMetalHost` and `Secret` resources: 1. Create a YAML file that defines the `BareMetalHost` and `Secret` resources: Example `ibi-bmh.yaml` file: ```yaml apiVersion: metal3.io/v1alpha1 kind: BareMetalHost metadata: name: namespace: ibi-ns spec: online: bootMACAddress: bmc: address: credentialsName: preprovisioningNetworkDataName: automatedCleaningMode: disabled externallyProvisioned: true --- apiVersion: v1 kind: Secret metadata: name: namespace: ibi-ns type: Opaque data: username: password: ``` where: `` : Specifies the name for the `BareMetalHost` resource, for example `ibi-bmh`. `` : Specifies if the host should be online, for example `false`. `` : Specifies the host boot MAC address, for example `00:a5:12:55:62:64`. `` : Specifies the BMC address, for example `redfish-virtualmedia+http://192.168.111.1:8000/redfish/v1/Systems/8a5babac-94d0-4c20-b282-50dc3a0a32b5`. You can only use bare-metal host drivers that support virtual media networking booting, for example redfish-virtualmedia and idrac-virtualmedia. `` : Specifies the name of the bare-metal host `Secret` resource, for example `ibi-bmh-bmc-secret`. `` : (Optional) Specifies the name of the `Secret` resource containing the static network configuration for the host, for example `host-network-config-secret`. `automatedCleaningMode: disabled` : Specifies that automated cleaning is disabled to prevent the provisioning service from deleting all preinstallation artifacts, such as the seed image, during disk inspection. `externallyProvisioned: true` : Specifies that the host is externally provisioned to enable it to boot from the preinstalled disk, instead of the configuration ISO. `` : Specifies the username for BMC authentication. `` : Specifies the password for BMC authentication. 2. Create the `BareMetalHost` and `Secret` resources by running the following command: ```terminal $ oc create -f ibi-bmh.yaml ``` 5. Create the `ClusterImageSet` resource: 1. Create a YAML file that defines the `ClusterImageSet` resource: Example `ibi-cluster-image-set.yaml` file: ```yaml apiVersion: hive.openshift.io/v1 kind: ClusterImageSet metadata: name: spec: releaseImage: ``` where: `` : Specifies the name for the `ClusterImageSet` resource, for example `ibi-img-version-arch`. `` : Specifies the address for the release image to use for the deployment, for example `ibi.example.com:path/to/release/images:version-arch`. If you use a different image registry compared to the image registry used during seed image generation, ensure that the OpenShift Container Platform version for the release image remains the same. 2. Create the `ClusterImageSet` resource by running the following command: ```terminal $ oc apply -f ibi-cluster-image-set.yaml ``` 6. Create the `ImageClusterInstall` resource: 1. Create a YAML file that defines the `ImageClusterInstall` resource: Example `ibi-image-cluster-install.yaml` file: ```yaml apiVersion: extensions.hive.openshift.io/v1alpha1 kind: ImageClusterInstall metadata: name: namespace: ibi-ns spec: bareMetalHostRef: name: namespace: ibi-ns clusterDeploymentRef: name: hostname: imageSetRef: name: machineNetworks: - cidr: 10.0.0.0/24 #- cidr: fd01::/64 proxy: httpProxy: "http://proxy.example.com:8080" #httpsProxy: "http://proxy.example.com:8080" #noProxy: "no_proxy.example.com" ``` where: `` : Specifies the name for the `ImageClusterInstall` resource, for example `ibi-image-install`. `` : Specifies the `BareMetalHost` resource that you want to target for the image-based installation, for example `ibi-bmh`. `` : Specifies the name of the `ClusterDeployment` resource that you want to use for the image-based installation of the target host, for example `ibi-cluster-deployment`. `` : Specifies the hostname for the cluster, for example `ibi-host`. `` : Specifies the name of the `ClusterImageSet` resource you used to define the container release images to use for deployment, for example `ibi-img-version-arch`. `machineNetworks` : Specifies the public Classless Inter-Domain Routing (CIDR) of the external network. For dual-stack networking, you can specify both IPv4 and IPv6 CIDRs using a list format. The first CIDR in the list is the primary address family and must match the primary address family of the seed cluster. `proxy` : (Optional) Specifies a proxy to use for the cluster deployment. > [!IMPORTANT] > If your cluster deployment requires a proxy configuration, you must do the following: > > - Create a seed image from a seed cluster featuring a proxy configuration. The proxy configurations do not have to match. > - Configure the `machineNetwork` field in your installation manifest. 2. Create the `ImageClusterInstall` resource by running the following command: ```terminal $ oc create -f ibi-image-cluster-install.yaml ``` 7. Create the `ClusterDeployment` resource: 1. Create a YAML file that defines the `ClusterDeployment` resource: Example `ibi-cluster-deployment.yaml` file: ```yaml apiVersion: hive.openshift.io/v1 kind: ClusterDeployment metadata: name: namespace: spec: baseDomain: clusterInstallRef: group: extensions.hive.openshift.io kind: ImageClusterInstall name: version: v1alpha1 clusterName: platform: none: {} pullSecretRef: name: ``` where: `` : Specifies the name for the `ClusterDeployment` resource, for example `ibi-cluster-deployment`. `` : Specifies the namespace for the `ClusterDeployment` resource, for example `ibi-ns`. `` : Specifies the base domain that the cluster should belong to, for example `example.com`. `` : Specifies the name of the `ImageClusterInstall` in which you defined the container images to use for the image-based installation of the target host, for example `ibi-image-install`. `` : Specifies a name for the cluster, for example `ibi-cluster`. `` : Specifies the secret to use for pulling images from your image registry, for example `ibi-image-pull-secret`. 2. Create the `ClusterDeployment` resource by running the following command: ```terminal $ oc apply -f ibi-cluster-deployment.yaml ``` 8. Create the `ManagedCluster` resource: 1. Create a YAML file that defines the `ManagedCluster` resource: Example `ibi-managed.yaml` file: ```yaml apiVersion: cluster.open-cluster-management.io/v1 kind: ManagedCluster metadata: name: spec: hubAcceptsClient: ``` where: `` : Specifies the name for the `ManagedCluster` resource, for example `sno-ibi`. `` : Specifies whether RHACM manages the cluster. Set to `true` to enable management. 2. Create the `ManagedCluster` resource by running the following command: ```terminal $ oc apply -f ibi-managed.yaml ``` **Verification** 1. Check the status of the `ImageClusterInstall` in the hub cluster to monitor the progress of the target host installation by running the following command: ```terminal $ oc get imageclusterinstall ``` Example output: ```terminal NAME REQUIREMENTSMET COMPLETED BAREMETALHOSTREF target-0 HostValidationSucceeded ClusterInstallationSucceeded ibi-bmh ``` > [!WARNING] > If the `ImageClusterInstall` resource is deleted, the IBI Operator reattaches the `BareMetalHost` resource and reboots the machine. 2. When the installation completes, you can retrieve the `kubeconfig` secret to log in to the managed cluster by running the following command: ```terminal $ oc extract secret/-admin-kubeconfig -n --to - > /-kubeconfig ``` where: `` : Specifies the name of the cluster. `` : Specifies the namespace of the cluster. `` : Specifies the directory in which to create the file. **Additional resources** {._additional-resources} - [Using image pull secrets](/openshift-docs-markdown/openshift_images/managing_images/using-image-pull-secrets) - [Cluster configuration resources for deploying a preinstalled host](/openshift-docs-markdown/edge_computing/image_base_install/ibi_deploying_sno_clusters/ibi-edge-image-based-install#ibi-managed-cluster-config-resources_ibi-edge-image-based-install) ### Cluster configuration resources for deploying a preinstalled host {#ibi-managed-cluster-config-resources_ibi-edge-image-based-install} To complete a deployment for a preinstalled host at a remote site, you must configure the following site-specifc cluster configuration resources in the hub cluster for each bare-metal host. **Cluster configuration resources reference** | Resource | Description | | --- | --- | | `Namespace` | Namespace for the managed single-node OpenShift cluster. | | `BareMetalHost` | Describes the physical host and its properties, such as the provisioning and hardware configuration. | | `Secret` for the bare-metal host | Credentials for the host BMC. | | `Secret` for the bare-metal host static network configuration | Optional: Describes static network configuration for the target host. | | `Secret` for the image registry | Credentials for the image registry. The secret for the image registry must be of type `kubernetes.io/dockerconfigjson`. | | `ImageClusterInstall` | References the bare-metal host, deployment, and image set resources. | | `ClusterImageSet` | Describes the release images to use for the cluster. | | `ClusterDeployment` | Describes networking, authentication, and platform-specific settings. | | `ManagedCluster` | Describes cluster details to enable Red Hat Advanced Cluster Management (RHACM) to register and manage. | | `ConfigMap` | Optional: Describes additional configurations for the cluster deployment, such as adding a bundle of trusted certificates for the host to ensure trusted communications for cluster services. | ### ImageClusterInstall resource API specifications {#ibi-image-cluster-install-api-spec_ibi-edge-image-based-install} The following content describes the API specifications for the `ImageClusterInstall` resource. This resource is the endpoint for the Image Based Install Operator. **Required specifications**
Specification Type Description
imageSetRef string Specify the name of the ClusterImageSet resource that defines the release images for the deployment.
hostname string Specify the hostname for the cluster.
sshKey string Specify your SSH key to provide SSH access to the target host.
**Optional specifications**
Specification Type Description
clusterDeploymentRef string Specify the name of the ClusterDeployment resource that you want to use for the image-based installation of the target host.
clusterMetadata string After the deployment completes, this specification is automatically populated with metadata information about the cluster, including the cluster-admin kubeconfig credentials for logging in to the cluster.
imageDigestSources string Specifies the sources or repositories for the release-image content, for example: [source,yaml] ---- imageDigestSources: - mirrors: - "registry.example.com:5000/ocp4/openshift4" source: "quay.io/openshift-release-dev/ocp-release" ----
extraManifestsRefs string Specify a ConfigMap resource containing additional manifests to be applied to the target cluster.
bareMetalHostRef string Specify the bareMetalHost resource to use for the cluster deployment
machineNetworks string Specify the public Classless Inter-Domain Routing (CIDR) of the external network. For dual-stack networking, you can specify both IPv4 and IPv6 CIDRs using a list format. The first CIDR in the list is the primary address family and must match the primary address family of the seed cluster.
proxy string Specifies proxy settings for the cluster, for example: [source,yaml]

---- proxy: httpProxy: "http://proxy.example.com:8080" httpsProxy: "http://proxy.example.com:8080" noProxy: "no_proxy.example.com" ----
caBundleRef string Specify a ConfigMap resource containing the new bundle of trusted certificates for the host.
## ConfigMap resources for extra manifests {#ibi-extra-manifests-configmap_ibi-edge-image-based-install} You can optionally create a `ConfigMap` resource to define additional manifests in an image-based deployment for managed single-node OpenShift clusters. After you create the `ConfigMap` resource, reference it in the `ImageClusterInstall` resource. During deployment, the IBI Operator includes the extra manifests in the deployment. ### Creating a ConfigMap resource to add extra manifests in an image-based deployment {#ibi-create-extra-manifest-configmap_ibi-edge-image-based-install} You can use a `ConfigMap` resource to add extra manifests to the image-based deployment for single-node OpenShift clusters. The following example adds an single-root I/O virtualization (SR-IOV) network to the deployment. > [!NOTE] > Filenames for extra manifests must not exceed 30 characters. Longer filenames might cause deployment failures. Before you begin, ensure that: - You preinstalled a host with single-node OpenShift using an image-based installation. - You logged in as a user with `cluster-admin` privileges. To create the `ConfigMap` resource, complete the following steps: 1. Create the `SriovNetworkNodePolicy` and `SriovNetwork` resources: 1. Create a YAML file that defines the resources, as in the following example: ```yaml apiVersion: sriovnetwork.openshift.io/v1 kind: SriovNetworkNodePolicy metadata: name: "example-sriov-node-policy" namespace: openshift-sriov-network-operator spec: deviceType: vfio-pci isRdma: false nicSelector: pfNames: [ens1f0] nodeSelector: node-role.kubernetes.io/master: "" mtu: 1500 numVfs: 8 priority: 99 resourceName: example-sriov-node-policy --- apiVersion: sriovnetwork.openshift.io/v1 kind: SriovNetwork metadata: name: "example-sriov-network" namespace: openshift-sriov-network-operator spec: ipam: |- { } linkState: auto networkNamespace: sriov-namespace resourceName: example-sriov-node-policy spoofChk: "on" trust: "off" ``` 2. Create the `ConfigMap` resource by running the following command: ```terminal $ oc create configmap sr-iov-extra-manifest --from-file=sriov-extra-manifest.yaml -n ``` where: `` : Specifies the namespace that has the `ImageClusterInstall` resource, for example `ibi-ns`. Example output: ```terminal configmap/sr-iov-extra-manifest created ``` > [!NOTE] > If you add more than one extra manifest, and the manifests must be applied in a specific order, you must prefix the filenames of the manifests with numbers that represent the required order. For example, `00-namespace.yaml`, `01-sriov-extra-manifest.yaml`, and so on. 2. Reference the `ConfigMap` resource in the `spec.extraManifestsRefs` field of the `ImageClusterInstall` resource: ```yaml #... spec: extraManifestsRefs: - name: sr-iov-extra-manifest #... ``` ### Creating a ConfigMap resource to add a CA bundle in an image-based deployment {#ibi-create-ca-extra-manifest-configmap_ibi-edge-image-based-install} You can use a `ConfigMap` resource to add a certificate authority (CA) bundle to the host to ensure trusted communications for cluster services. After you create the `ConfigMap` resource, reference it in the `spec.caBundleRef` field of the `ImageClusterInstall` resource. Before you begin, ensure that: - You preinstalled a host with single-node OpenShift using an image-based installation. - You logged in as a user with `cluster-admin` privileges. To create the CA bundle `ConfigMap` resource, complete the following steps: 1. Create a CA bundle file called `tls-ca-bundle.pem`, as in the following example: ```text -----BEGIN CERTIFICATE----- MIIDXTCCAkWgAwIBAgIJAKmjYKJbIyz3MA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV ...Custom CA certificate bundle... 4WPl0Qb27Sb1xZyAsy1ww6MYb98EovazUSfjYr2EVF6ThcAPu4/sMxUV7He2J6Jd cA8SMRwpUbz3LXY= -----END CERTIFICATE----- ``` 2. Create the `ConfigMap` object by running the following command: ```terminal $ oc create configmap custom-ca --from-file=tls-ca-bundle.pem -n ibi-ns ``` where: `custom-ca` : Specifies the name for the `ConfigMap` resource. `tls-ca-bundle.pem` : Specifies the key for the `data` entry in the `ConfigMap` resource. You must include a `data` entry with the `tls-ca-bundle.pem` key. `ibi-ns` : Specifies the namespace that has the `ImageClusterInstall` resource. Example output: ```terminal configmap/custom-ca created ``` 3. Reference the `ConfigMap` resource in the `spec.caBundleRef` field of the `ImageClusterInstall` resource: ```yaml #... spec: caBundleRef: name: custom-ca #... ``` **Additional resources** {._additional-resources} - [About the BareMetalHost resource](/openshift-docs-markdown/installing/installing_bare_metal/bare-metal-postinstallation-configuration#bmo-about-the-baremetalhost-resource_bare-metal-postinstallation-configuration) - [Using image pull secrets](/openshift-docs-markdown/openshift_images/managing_images/using-image-pull-secrets) - [Reference specifications for the image-based-config.yaml manifest](/openshift-docs-markdown/edge_computing/image_base_install/ibi-factory-image-based-install#ibi-installer-installation-config_ibi-factory-image-based-install)