OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

About image-based deployments for single-node OpenShift

You can manually generate a configuration ISO by using the openshift-install program. Attach the configuration ISO to your preinstalled target host to complete the deployment.

Deploying a single-node OpenShift cluster using the openshift-install program

You can use the openshift-install program to configure and deploy a host that you preinstalled with an image-based installation. To configure the target host with site-specific details, you must create the following resources:

  • The install-config.yaml installation manifest

  • The image-based-config.yaml manifest

The openshift-install program uses these resources to generate a configuration ISO that you attach to the preinstalled target host to complete the deployment.

For more information about the specifications for the image-based-config.yaml manifest, see "Reference specifications for the image-based-config.yaml manifest".
Prerequisites

  • You preinstalled a host with single-node OpenShift using an image-based installation.

  • You downloaded the latest version of the openshift-install program.

  • You created a pull secret to authenticate pull requests. For more information, see "Using image pull secrets".

Procedure

  1. Create a working directory by running the following:

    $ mkdir ibi-config-iso-workdir (1)
    1 Replace ibi-config-iso-workdir with the name of your working directory.

  2. Create the installation manifest:

    1. Create a YAML file that defines the install-config manifest:

      Example install-config.yaml file
      apiVersion: v1
metadata:
  name: sno-cluster-name
baseDomain: host.example.com
compute:
  - architecture: amd64
    hyperthreading: Enabled
    name: worker
    replicas: 0
controlPlane:
  architecture: amd64
  hyperthreading: Enabled
  name: master
  replicas: 1
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  machineNetwork:
  - cidr: 192.168.200.0/24
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
fips: false
cpuPartitioningMode: "AllNodes"
pullSecret: '{"auths":{"<your_pull_secret>"}}}'
sshKey: 'ssh-rsa <your_ssh_pub_key>'

      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. Save the file in your working directory.

  3. Optional. Create a configuration template in your working directory by running the following command:

    $ openshift-install image-based create config-template --dir ibi-config-iso-workdir/
    Example output
    INFO Config-Template created in: ibi-config-iso-workdir

    The command creates the image-based-config.yaml configuration template in your working directory:

    #
# Note: This is a sample ImageBasedConfig file showing
# which fields are available to aid you in creating your
# own image-based-config.yaml file.
#
apiVersion: v1beta1
kind: ImageBasedConfig
metadata:
  name: example-image-based-config
additionalNTPSources:
  - 0.rhel.pool.ntp.org
  - 1.rhel.pool.ntp.org
hostname: change-to-hostname
releaseRegistry: quay.io
# networkConfig contains the network configuration for the host in NMState format.
# See https://nmstate.io/examples.html for examples.
networkConfig:
  interfaces:
    - name: eth0
      type: ethernet
      state: up
      mac-address: 00:00:00:00:00:00
      ipv4:
        enabled: true
        address:
          - ip: 192.168.122.2
            prefix-length: 23
        dhcp: false

  4. Edit your configuration file:

    Example image-based-config.yaml file
    #
# Note: This is a sample ImageBasedConfig file showing
# which fields are available to aid you in creating your
# own image-based-config.yaml file.
#
apiVersion: v1beta1
kind: ImageBasedConfig
metadata:
  name: sno-cluster-name
additionalNTPSources:
  - 0.rhel.pool.ntp.org
  - 1.rhel.pool.ntp.org
hostname: host.example.com
releaseRegistry: quay.io
# networkConfig contains the network configuration for the host in NMState format.
# See https://nmstate.io/examples.html for examples.
networkConfig:
    interfaces:
      - name: ens1f0
        type: ethernet
        state: up
        ipv4:
          enabled: true
          dhcp: false
          auto-dns: false
          address:
            - ip: 192.168.200.25
              prefix-length: 24
        ipv6:
          enabled: false
    dns-resolver:
      config:
        server:
          - 192.168.15.47
          - 192.168.15.48
    routes:
      config:
      - destination: 0.0.0.0/0
        metric: 150
        next-hop-address: 192.168.200.254
        next-hop-interface: ens1f0

  5. Create the configuration ISO in your working directory by running the following command:

    $ openshift-install image-based create config-image --dir ibi-config-iso-workdir/
    Example output
    INFO Adding NMConnection file <ens1f0.nmconnection>
INFO Consuming Install Config from target directory
INFO Consuming Image-based Config ISO configuration from target directory
INFO Config-Image created in: ibi-config-iso-workdir/auth

    View the output in the working directory:

    Example output
    ibi-config-iso-workdir/
├── auth
│   ├── kubeadmin-password
│   └── kubeconfig
└── imagebasedconfig.iso

  6. Attach the imagebasedconfig.iso to the preinstalled host using your preferred method and restart the host to complete the configuration process and deploy the cluster.

Verification

When the configuration process completes on the host, access the cluster to verify its status.

  1. Export the kubeconfig environment variable to your kubeconfig file by running the following command:

    $ export KUBECONFIG=ibi-config-iso-workdir/auth/kubeconfig

  2. Verify that the cluster is responding by running the following command:

    $ oc get nodes
    Example output
    NAME                                         STATUS   ROLES                  AGE     VERSION
node/sno-cluster-name.host.example.com       Ready    control-plane,master   5h15m   v1.30.3
Additional resources

Reference specifications for the image-based-config.yaml manifest

The following content describes the specifications for the image-based-config.yaml manifest.

The openshift-install program uses the image-based-config.yaml manifest to create a site-specific configuration ISO for image-based deployments of single-node OpenShift.

Table 1. Required specifications
Specification Type Description

hostname

string

Define the name of the node for the single-node OpenShift cluster.
Table 2. Optional specifications
Specification Type Description

networkConfig

string

Specifies networking configurations for the host, for example:

networkConfig:
    interfaces:
      - name: ens1f0
        type: ethernet
        state: up
        ...

If you require static networking, you must install the nmstatectl library on the host that creates the live installation ISO. For further information about defining network configurations by using nmstate, see nmstate.io.

The name of the interface must match the actual NIC name as shown in the operating system.

additionalNTPSources

string

Specifies a list of NTP sources for all cluster hosts. These NTP sources are added to any existing NTP sources in the cluster. You can use the hostname or IP address for the NTP source.

releaseRegistry

string

Specifies the container image registry that you used for the release image of the seed cluster.

nodeLabels

map[string]string

Specifies custom node labels for the single-node OpenShift node, for example:

nodeLabels:
  node-role.kubernetes.io/edge: true
  environment: production

Configuring resources for extra manifests

You can optionally define additional resources in an image-based deployment for single-node OpenShift clusters.

Create the additional resources in an extra-manifests folder in the same working directory that has the install-config.yaml and image-based-config.yaml manifests.

Creating a resource in the extra-manifests folder

You can create a resource in the extra-manifests folder of your working directory 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.

Prerequisites

  • You created a working directory with the install-config.yaml and image-based-config.yaml manifests

Procedure

  1. Go to your working directory and create the extra-manifests folder by running the following command:

    $ mkdir extra-manifests

  2. Create the SriovNetworkNodePolicy and SriovNetwork resources in the extra-manifests folder:

    1. Create a YAML file that defines the resources:

      Example sriov-extra-manifest.yaml file
      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"
Verification

  • When you create the configuration ISO, you can view the reference to the extra manifests in the .openshift_install_state.json file in your working directory:

     "*configimage.ExtraManifests": {
        "FileList": [
            {
                "Filename": "extra-manifests/sriov-extra-manifest.yaml",
                "Data": "YXBFDFFD..."
            }
        ]
    }