Building OCK Images Examples

Provides examples of using the ock-forge script to build and customize standard OCK images.

This chapter shows how to use the Oracle Container Host for Kubernetes Image Builder to build standard OCK images for Oracle CNE deployments, and how these OCK images can be customized using first-boot host customization through extraIgnitionInline using Butane.

Building Standard OCK Images

Provides examples of using the ock-forge script to build standard OCK images.

Example 4-1 Building a typical Qcow2 image

A typical invocation builds Qcow2 images. The ock-forge script does all the work required. This example generates a new Qcow2 image, attaches it as a block device, partitions the disk, formats the partitions, installs the OS, and generates an OSTree archive:

sudo ./ock-forge -d /dev/nbd0 -D out/1.33/boot.qcow2 \
                -i container-registry.oracle.com/olcne/ock-ostree:1.33 \
                -O ./out/1.33/archive.tar \
                -C ./ock -c configs/config-1.33 -P

Example 4-2 Building a Qcow2 image from GitHub

The ock-forge script can copy configurations from inconvenient places to more convenient places. This example builds a Qcow2 and OSTree image from scratch, using the OCK GitHub repository as a source of truth. The clone of the repository is retained and can be reused in later invocations:

sudo ./ock-forge -d /dev/nbd0 -D out/1.33/boot.qcow2 \
                -i container-registry.oracle.com/olcne/ock-ostree:1.33 \
                -O ./out/1.33/archive.tar \
                -C ./ock -c configs/config-1.33 \
                -s https://github.com/oracle-cne/ock.git -P

Example 4-3 Build a raw disk image

This example generates a raw disk image, rather than a Qcow2 image. The generated image can be dd'ed onto a physical disk, and used to boot a system directly:

sudo ./ock-forge -d /dev/loop0 -D out/1.33/boot.iso \
                -i container-registry.oracle.com/olcne/ock-ostree:1.33 \
                -O ./out/1.33/archive.tar \
                -C ./ock -c configs/config-1.33 -P

Example 4-4 Install to a physical disk

This example installs the image to a physical block device, creating the necessary partitions:

sudo ./ock-forge -d /dev/sdb \
                -i container-registry.oracle.com/olcne/ock-ostree:1.33 \
                -O ./out/1.33/archive.tar \
                -C ./ock -c configs/config-1.33 -P

Example 4-5 Install but don't generate OSTree archive

This example performs a fresh installation of the OS, but doesn't store the contents in an OSTree container image archive:

sudo ./ock-forge -d /dev/nbd0 -C ./ock -c configs/config-1.33 -P

Example 4-6 Install from a container image

This example installs the OS using an existing OSTree container image as the source:

sudo ./ock-forge -d /dev/nbd0 -d /dev/loop0 -D out/1.33/boot.iso \
                -i container-registry.oracle.com/olcne/ock-ostree:1.33 -P

Customizing Standard OCK Images

Provides examples of using Ignition files to customize standard OCK images.

Customizing standard OCK images

The following examples show how to use a YAML configuration file, located in the ~/.ocne/defaults.yaml directory, which conforms to the Butane schema to generate an Ignition config file that's used to customize a standard OCK image through extraIgnitionInline during its first boot.

Example 4-7 Create a user

This example creates a new user:

extraIgnitionInline: |
  variant: fcos
  version: 1.5.0  
                
  passwd:
    users:
      - name: NAME_OF_USER
        home_dir: PATH_TO_YOUR_HOME_DIRECTORY
        groups:
          - NAME_OF_USERS_GROUP
        ssh_authorized_keys:
          - YOUR_PUBLIC_KEY

Example 4-8 Create a directory

This example shows how to create a directory and assign permissions to it:

extraIgnitionInline: | 
  variant: fcos 
  version: 1.5.0 
                
  storage:
    directories:
      - path: PATH_TO_DIRECTORY_TO_CREATE
        mode: OCTAL_FILE_PERMISISON_VALUE
        user:
          name: USERS_NAME
        group:
          name: USERS_GROUP

Example 4-9 Create a text file in a directory

This example shows how to create a file in a directory and assign permissions to it:

extraIgnitionInline: | 
  variant: fcos 
  version: 1.5.0 

  storage:
    files:
      - path: PATH_TO_FILE_TO_CREATE
        mode: OCTAL_FILE_PERMISISON_VALUE
        user:
          name: USERS_NAME
        group:
          name: USERS_GROUP
        overwrite: true
        contents:
          inline: |
            Hello from Oracle CNE on OCK.
            This file was created at first boot by extraIgnitionInline.

Example 4-10 Change the Message of the Day file

This example shows how to change the Message of the Day file:

extraIgnitionInline: | 
  variant: fcos 
  version: 1.5.0
  
  storage:
    files:  
      - path: /etc/motd
        mode: 0644
        overwrite: true
        contents:
          inline: |
            Oracle CNE custom OCK node
            Example user customization enabled
            Current Kubernetes version: 1.33

Example 4-11 Set the root partition size

This example shows how to set the root partition size to 30Gb and use the rest of the disk as another partition:

extraIgnitionInline: |
  variant: fcos
  version: 1.5.0
  
  storage:
    disks:
    - device: /dev/sda
      wipe_table: false
      partitions:
      - label: lvm1
        number: 4
        start_mib: 30720

Example 4-12 Enable a first-boot systemd Service

This example shows how to configure systemd to enable a first-boot audit service:

extraIgnitionInline: |
  variant: fcos
  version: 1.5.0

  systemd:
    units:
      - name: bootstrap-audit.service
        enabled: true
        contents: |
          [Unit]
          Description=Audit first boot customization
          After=network-online.target
          Wants=network-online.target

          [Service]
          Type=oneshot
          ExecStart=/usr/bin/bash -c 'date > /var/log/first-boot-audit.log'

          [Install]
          WantedBy=multi-user.target

Example 4-13 Create and merge two disk partitions then create a new mount point.

This example shows how to create two partitions, then join them using Logical Volume Manager and mount them to a new mount point (/var/lvtest):

extraIgnitionInline: |
  variant: fcos
  version: 1.5.0
  
  storage:
    disks:
    - device: /dev/sda
      wipe_table: false
      partitions:
      - label: lvm1
        number: 4
        start_mib: 30720
        size_mib: 70000
      - label: lvm2
        number: 5
    directories:
      - path: /var/lvtest
    files:
      - path: /etc/lvscript.sh
        mode: 755
        contents:
          inline: |
            #! /bin/bash
            set -x
            if [ -b /dev/mapper/bdgroup-bdvol ]; then exit 0; fi
            pvcreate /dev/sda4 /dev/sda5
            vgcreate bdgroup /dev/sda4 /dev/sda5
            lvcreate -L 30GB -n bdvol bdgroup
            mkfs.xfs /dev/mapper/bdgroup-bdvol
            UUID=$(blkid -s UUID -o value /dev/mapper/bdgroup-bdvol)
            systemctl set-environment BDVOL_UUID=$UUID
            mkdir /etc/systemd/system/var-lvtest.mount.d
            cat > /etc/systemd/system/var-lvtest.mount.d/uuid.conf << EOF
            [Mount]
            Environment=BDVOL_UUID=$UUID
            EOF
  systemd:
    units:
      - name: lvsetup.service
        enabled: true
        contents: |
          [Service]
          Type=oneshot
          ExecStart=/etc/lvscript.sh

          [Install]
          WantedBy=multi-user.target
      - name: var-lvtest.mount
        enabled: true
        contents: |
          [Unit]
          After=lvsetup.service

          [Mount]
          What=UUID=${BDVOL_UUID}
          Where=/var/lvtest
          Type=xfs
          Options=defaults

          [Install]
          WantedBy=multi-user.target

Example 4-14 Define several services in a single file

This example shows how to showing how several services could be defined in a single definition file:

extraIgnitionInline: |
  variant: fcos
  version: 1.5.0

  passwd:
    users:
      - name: appuser
        # Sets the intended home directory for the account.
        home_dir: /home/appuser
        # Adds the user to the wheel group for administrative access.
        groups:
          - wheel
        # Replace this with a real public key for customer testing.
        ssh_authorized_keys:
          - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI_REPLACE_WITH_YOUR_PUBLIC_KEY

  storage:
    directories:
      - path: /home/appuser
        # Explicitly creates the user's home directory and sets ownership.
        mode: 0755
        user:
          name: appuser
        group:
          name: appuser

    files:
      - path: /home/appuser/README.txt
        # Creates a text file in the user's home directory.
        mode: 0644
        user:
          name: appuser
        group:
          name: appuser
        overwrite: true
        contents:
          inline: |
            Hello from Oracle CNE on OCK for Kubernetes 1.32.
            This file was created at first boot by extraIgnitionInline.

      - path: /etc/motd
        mode: 0644
        overwrite: true
        contents:
          inline: |
            Oracle CNE custom OCK node
            Example user customization enabled
            Kubernetes target: 1.32