Skip to content

TELCODOCS-2686 DITA rewrite for ibi-edge-image-based-install.adoc #106507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rohennes wants to merge 1 commit into
base: main
Choose a base branch
from
Open

TELCODOCS-2686 DITA rewrite for ibi-edge-image-based-install.adoc #106507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 93 additions & 72 deletions modules/ibi-create-config-iso.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
[id="ibi-create-config-iso_{context}"]
= Deploying a managed {sno} cluster using the IBI Operator

[role="_abstract"]
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 {sno} cluster is ready.
Expand Down Expand Up @@ -45,10 +46,13 @@ metadata:
name: ibi-image-pull-secret
namespace: ibi-ns
stringData:
.dockerconfigjson: <base64-docker-auth-code> <1>
.dockerconfigjson: <base64_docker_auth_code>
type: kubernetes.io/dockerconfigjson
----
<1> You must provide base64-encoded credential details. See the "Additional resources" section for more information about using image pull secrets.
+
where:
+
`<base64_docker_auth_code>`:: Specifies base64-encoded credential details. See the "Additional resources" section for more information about using image pull secrets.

.. Create the `Secret` resource for your image registry by running the following command:
+
Expand All @@ -67,42 +71,45 @@ $ oc create -f secret-image-registry.yaml
apiVersion: v1
kind: Secret
metadata:
name: host-network-config-secret <1>
name: <network_secret_name>
namespace: ibi-ns
type: Opaque
stringData:
nmstate: | <2>
nmstate: |
interfaces:
- name: ens1f0 <3>
- name: <interface_name>
type: ethernet
state: up
ipv4:
enabled: true
address:
- ip: 192.168.200.25
prefix-length: 24
dhcp: false <4>
dhcp: false
ipv6:
enabled: false
dns-resolver:
config:
server:
- 192.168.15.47 <5>
- <dns_server_1>
- 192.168.15.48
routes:
config: <6>
config:
- destination: 0.0.0.0/0
metric: 150
next-hop-address: 192.168.200.254
next-hop-interface: ens1f0
next-hop-interface: <interface_name>
table-id: 254
----
<1> Specify the name for the `Secret` resource.
<2> Define the static network configuration in `nmstate` format.
<3> Specify the name of the interface on the host. 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`.
<4> You must specify `dhcp: false` to ensure `nmstate` assigns the static IP address to the interface.
<5> Specify one or more DNS servers that the system will use to resolve domain names.
<6> In this example, the default route is configured through the `ens1f0` interface to the next hop IP address `192.168.200.254`.
+
where:
+
`<network_secret_name>`:: Specifies the name for the `Secret` resource, for example `host-network-config-secret`.
`nmstate`:: Defines the static network configuration in `nmstate` format.
`<interface_name>`:: 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`:: You must specify `dhcp: false` to ensure `nmstate` assigns the static IP address to the interface.
`<dns_server_1>`:: Specifies one or more DNS servers that the system will use to resolve domain names, for example `192.168.15.47`.
`config`:: In this example, the default route is configured through the `ens1f0` interface to the next hop IP address `192.168.200.254`.

. Create the `BareMetalHost` and `Secret` resources:

Expand All @@ -114,39 +121,41 @@ stringData:
apiVersion: metal3.io/v1alpha1
kind: BareMetalHost
metadata:
name: ibi-bmh <1>
name: <baremetalhost_name>
namespace: ibi-ns
spec:
online: false <2>
bootMACAddress: 00:a5:12:55:62:64 <3>
online: <online_status>
bootMACAddress: <boot_mac_address>
bmc:
address: redfish-virtualmedia+http://192.168.111.1:8000/redfish/v1/Systems/8a5babac-94d0-4c20-b282-50dc3a0a32b5 <4>
credentialsName: ibi-bmh-bmc-secret <5>
preprovisioningNetworkDataName: host-network-config-secret <6>
automatedCleaningMode: disabled <7>
externallyProvisioned: true <8>
address: <bmc_address>
credentialsName: <bmh_secret_name>
preprovisioningNetworkDataName: <network_secret_name>
automatedCleaningMode: disabled
externallyProvisioned: true
---
apiVersion: v1
kind: Secret
metadata:
name: ibi-bmh-secret <9>
name: <bmh_secret_name>
namespace: ibi-ns
type: Opaque
data:
username: <user_name> <10>
password: <password> <11>
----
<1> Specify the name for the `BareMetalHost` resource.
<2> Specify if the host should be online.
<3> Specify the host boot MAC address.
<4> Specify the BMC address. You can only use bare-metal host drivers that support virtual media networking booting, for example redfish-virtualmedia and idrac-virtualmedia.
<5> Specify the name of the bare-metal host `Secret` resource.
<6> Optional: If you require static network configuration for the host, specify the name of the `Secret` resource containing the configuration.
<7> You must specify `automatedCleaningMode:disabled` to prevent the provisioning service from deleting all preinstallation artifacts, such as the seed image, during disk inspection.
<8> You must specify `externallyProvisioned: true` to enable the host to boot from the preinstalled disk, instead of the configuration ISO.
<9> Specify the name for the `Secret` resource.
<10> Specify the username.
<11> Specify the password.
username: <username>
password: <password>
----
+
where:
+
`<baremetalhost_name>`:: Specifies the name for the `BareMetalHost` resource, for example `ibi-bmh`.
`<online_status>`:: Specifies if the host should be online, for example `false`.
`<boot_mac_address>`:: Specifies the host boot MAC address, for example `00:a5:12:55:62:64`.
`<bmc_address>`:: 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.
`<bmh_secret_name>`:: Specifies the name of the bare-metal host `Secret` resource, for example `ibi-bmh-bmc-secret`.
`<network_secret_name>`:: (Optional) If you require static network configuration for the host, specify the name of the `Secret` resource containing the configuration, for example `host-network-config-secret`.
`automatedCleaningMode: disabled`:: You must specify `automatedCleaningMode:disabled` to prevent the provisioning service from deleting all preinstallation artifacts, such as the seed image, during disk inspection.
`externallyProvisioned: true`:: You must specify `externallyProvisioned: true` to enable the host to boot from the preinstalled disk, instead of the configuration ISO.
`<username>`:: Specifies the username for BMC authentication.
`<password>`:: Specifies the password for BMC authentication.

.. Create the `BareMetalHost` and `Secret` resources by running the following command:
+
Expand All @@ -165,12 +174,15 @@ $ oc create -f ibi-bmh.yaml
apiVersion: hive.openshift.io/v1
kind: ClusterImageSet
metadata:
name: ibi-img-version-arch <1>
name: <clusterimageset_name>
spec:
releaseImage: ibi.example.com:path/to/release/images:version-arch <2>
releaseImage: <release_image>
----
<1> Specify the name for the `ClusterImageSet` resource.
<2> Specify the address for the release image to use for the deployment. If you use a different image registry compared to the image registry used during seed image generation, ensure that the {product-title} version for the release image remains the same.
+
where:
+
`<clusterimageset_name>`:: Specifies the name for the `ClusterImageSet` resource, for example `ibi-img-version-arch`.
`<release_image>`:: 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 {product-title} version for the release image remains the same.

.. Create the `ClusterImageSet` resource by running the following command:
+
Expand All @@ -189,32 +201,35 @@ $ oc apply -f ibi-cluster-image-set.yaml
apiVersion: extensions.hive.openshift.io/v1alpha1
kind: ImageClusterInstall
metadata:
name: ibi-image-install <1>
name: <imageclusterinstall_name>
namespace: ibi-ns
spec:
bareMetalHostRef:
name: ibi-bmh <2>
name: <baremetalhost_name>
namespace: ibi-ns
clusterDeploymentRef:
name: ibi-cluster-deployment <3>
hostname: ibi-host <4>
name: <clusterdeployment_name>
hostname: <cluster_hostname>
imageSetRef:
name: ibi-img-version-arch <5>
machineNetworks: <6>
name: <clusterimageset_name>
machineNetworks:
- cidr: 10.0.0.0/24
#- cidr: fd01::/64
proxy: <7>
proxy:
httpProxy: "http://proxy.example.com:8080"
#httpsProxy: "http://proxy.example.com:8080"
#noProxy: "no_proxy.example.com"
----
<1> Specify the name for the `ImageClusterInstall` resource.
<2> Specify the `BareMetalHost` resource that you want to target for the image-based installation.
<3> Specify the name of the `ClusterDeployment` resource that you want to use for the image-based installation of the target host.
<4> Specify the hostname for the cluster.
<5> Specify the name of the `ClusterImageSet` resource you used to define the container release images to use for deployment.
<6> 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.
<7> Optional: Specify a proxy to use for the cluster deployment.
+
where:
+
`<imageclusterinstall_name>`:: Specifies the name for the `ImageClusterInstall` resource, for example `ibi-image-install`.
`<baremetalhost_name>`:: Specifies the `BareMetalHost` resource that you want to target for the image-based installation, for example `ibi-bmh`.
`<clusterdeployment_name>`:: 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`.
`<cluster_hostname>`:: Specifies the hostname for the cluster, for example `ibi-host`.
`<clusterimageset_name>`:: 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]
====
Expand All @@ -241,27 +256,30 @@ $ oc create -f ibi-image-cluster-install.yaml
apiVersion: hive.openshift.io/v1
kind: ClusterDeployment
metadata:
name: ibi-cluster-deployment <1>
namespace: ibi-ns <2>
name: <clusterdeployment_name>
namespace: <namespace>
spec:
baseDomain: example.com <3>
baseDomain: <base_domain>
clusterInstallRef:
group: extensions.hive.openshift.io
kind: ImageClusterInstall
name: ibi-image-install <4>
name: <imageclusterinstall_name>
version: v1alpha1
clusterName: ibi-cluster <5>
clusterName: <cluster_name>
platform:
none: {}
pullSecretRef:
name: ibi-image-pull-secret <6>
name: <pull_secret_name>
----
<1> Specify the name for the `ClusterDeployment` resource.
<2> Specify the namespace for the `ClusterDeployment` resource.
<3> Specify the base domain that the cluster should belong to.
<4> Specify the name of the `ImageClusterInstall` in which you defined the container images to use for the image-based installation of the target host.
<5> Specify a name for the cluster.
<6> Specify the secret to use for pulling images from your image registry.
+
where:
+
`<clusterdeployment_name>`:: Specifies the name for the `ClusterDeployment` resource, for example `ibi-cluster-deployment`.
`<namespace>`:: Specifies the namespace for the `ClusterDeployment` resource, for example `ibi-ns`.
`<base_domain>`:: Specifies the base domain that the cluster should belong to, for example `example.com`.
`<imageclusterinstall_name>`:: 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`.
`<cluster_name>`:: Specifies a name for the cluster, for example `ibi-cluster`.
`<pull_secret_name>`:: Specifies the secret to use for pulling images from your image registry, for example `ibi-image-pull-secret`.

.. Create the `ClusterDeployment` resource by running the following command:
+
Expand All @@ -280,12 +298,15 @@ $ oc apply -f ibi-cluster-deployment.yaml
apiVersion: cluster.open-cluster-management.io/v1
kind: ManagedCluster
metadata:
name: sno-ibi <1>
name: <managedcluster_name>
spec:
hubAcceptsClient: true <2>
hubAcceptsClient: <hub_accepts_client>
----
<1> Specify the name for the `ManagedCluster` resource.
<2> Specify `true` to enable {rh-rhacm} to manage the cluster.
+
where:
+
`<managedcluster_name>`:: Specifies the name for the `ManagedCluster` resource, for example `sno-ibi`.
`<hub_accepts_client>`:: Specify `true` to enable {rh-rhacm} to manage the cluster.

.. Create the `ManagedCluster` resource by running the following command:
+
Expand Down
25 changes: 12 additions & 13 deletions modules/ibi-extra-manifests-configmap.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
//
// * edge_computing/ibi-edge-image-based-install.adoc

:_mod-docs-content-type: CONCEPT
:_mod-docs-content-type: REFERENCE
[id="ibi-extra-manifests-configmap_{context}"]
= ConfigMap resources for extra manifests

[role="_abstract"]
You can optionally create a `ConfigMap` resource to define additional manifests in an image-based deployment for managed {sno} 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.
Expand All @@ -19,21 +20,19 @@ The following example adds an single-root I/O virtualization (SR-IOV) network to

[NOTE]
====
Filenames for extra manifests must not exceed 30 characters. Longer filenames might cause deployment failures.
Filenames for extra manifests must not exceed 30 characters. Longer filenames might cause deployment failures.
====

.Prerequisites
Before you begin, ensure that:

* You preinstalled a host with {sno} using an image-based installation.
* You logged in as a user with `cluster-admin` privileges.

.Procedure
To create the `ConfigMap` resource, complete the following steps:

. Create the `SriovNetworkNodePolicy` and `SriovNetwork` resources:

.. Create a YAML file that defines the resources:
+
.Example `sriov-extra-manifest.yaml` file
.. Create a YAML file that defines the resources, as in the following example:
+
[source,yaml]
----
Expand Down Expand Up @@ -74,9 +73,10 @@ spec:
+
[source,terminal]
----
$ oc create configmap sr-iov-extra-manifest --from-file=sriov-extra-manifest.yaml -n ibi-ns <1>
$ oc create configmap sr-iov-extra-manifest --from-file=sriov-extra-manifest.yaml -n <namespace>
----
<1> Specify the namespace that has the `ImageClusterInstall` resource.
+
where `<namespace>` specifies the namespace that has the `ImageClusterInstall` resource, for example `ibi-ns`.
+
.Example output
[source,terminal]
Expand Down Expand Up @@ -107,16 +107,15 @@ You can use a `ConfigMap` resource to add a certificate authority (CA) bundle to

After you create the `ConfigMap` resource, reference it in the `spec.caBundleRef` field of the `ImageClusterInstall` resource.

.Prerequisites
Before you begin, ensure that:

* You preinstalled a host with {sno} using an image-based installation.
* You logged in as a user with `cluster-admin` privileges.

.Procedure
To create the CA bundle `ConfigMap` resource, complete the following steps:

. Create a CA bundle file called `tls-ca-bundle.pem`:
. Create a CA bundle file called `tls-ca-bundle.pem`, as in the following example:
+
.Example `tls-ca-bundle.pem` file
[source,text]
----
-----BEGIN CERTIFICATE-----
Expand Down
1 change: 1 addition & 0 deletions modules/ibi-image-cluster-install-api-spec.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
[id="ibi-image-cluster-install-api-spec_{context}"]
= ImageClusterInstall resource API specifications

[role="_abstract"]
The following content describes the API specifications for the `ImageClusterInstall` resource. This resource is the endpoint for the Image Based Install Operator.

.Required specifications
Expand Down
1 change: 1 addition & 0 deletions modules/ibi-install-ibi-operator.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
[id="ibi-install-ibi-operator_{context}"]
= Installing the Image Based Install Operator

[role="_abstract"]
The Image Based Install (IBI) Operator is part of the image-based deployment workflow for preinstalled {sno} on bare-metal hosts.

[NOTE]
Expand Down
3 changes: 2 additions & 1 deletion modules/ibi-managed-cluster-config-resources.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
//
// * edge_computing/ibi-edge-image-based-install.adoc

:_mod-docs-content-typetent-type: REFERENCE
:_mod-docs-content-type: REFERENCE
[id="ibi-managed-cluster-config-resources_{context}"]
= Cluster configuration resources for deploying a preinstalled host

[role="_abstract"]
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
Expand Down