Custom OS Images

croit OS images are standard OCI images. You can extend a croit image with your own packages, configuration files, certificates, or systemd services, publish the result to a container registry, and use it on your cluster nodes.

croit downloads the OCI image to the management node and converts it to the files used by the existing network boot process. Cluster nodes do not need access to your registry.

Before you start

You need:

• A container registry that the croit management node can reach.
• Permission to push images to that registry.
• An OCI image builder, such as Docker Buildx, Podman, or Buildah.
• A croit image that matches your cluster's Ceph release, Ceph variant, and processor architecture.

Use a released croit image as the parent. This preserves the kernel, initramfs, Ceph packages, and image metadata that croit needs. Do not build a boot image from an unrelated Linux image.

Create a custom image

The following example adds an RPM, its configuration, and a systemd service to a croit image:

FROM oci.croit.io/croit/os:tentacle-enhanced.v2609

COPY example-agent.rpm /tmp/example-agent.rpm
RUN microdnf -y install /tmp/example-agent.rpm \
    && rm /tmp/example-agent.rpm \
    && microdnf clean all \
    && systemctl enable example-agent.service

COPY example-agent.conf /etc/example-agent/example-agent.conf

LABEL io.croit.description="Tentacle with Example Agent"

Replace the parent tag with the release used by your cluster. The tag identifies the Ceph release, Ceph variant, and croit release. The example uses tentacle-enhanced.v2609, but you can extend any compatible released croit image.

Build and push the image with OCI media types. For example, with Docker Buildx:

docker buildx build \
  --platform linux/amd64 \
  --output type=image,name=registry.example.com/storage/croit-os:example-agent-v1,push=true,oci-mediatypes=true \
  .

Use linux/arm64 for ARM nodes. You can build a multi-architecture image with --platform linux/amd64,linux/arm64 when the parent image and your added software support both architectures.

Use a new tag for each build. This makes rollbacks predictable and prevents a cluster from seeing different content under a reference it already uses.

Packages from deprecated Extended images

Extended images are deprecated. Customers who used them are encouraged to publish a custom image based on any compatible released croit image to their own OCI registry. Add only the packages you use. You do not need to recreate the complete Extended package set.

Use the following Dockerfile only when you need the same packages that the old Extended image provided:

FROM oci.croit.io/croit/os:tentacle-enhanced.v2609

RUN printf '%s\n' \
      '[influxdata]' \
      'name = InfluxData Repository - Stable' \
      'baseurl = https://repos.influxdata.com/stable/$basearch/main' \
      'enabled = 1' \
      'gpgcheck = 1' \
      'gpgkey = https://repos.influxdata.com/influxdata-archive.key' \
      > /etc/yum.repos.d/influxdata.repo && \
    rpm --import https://repos.influxdata.com/influxdata-archive.key && \
    dnf -y $DNF_OPTS install \
      ansible \
      bird \
      gdb \
      iftop \
      ipset \
      libcap \
      netdata \
      python3-netaddr \
      rsyslog \
      salt-minion \
      telegraf \
      valgrind

For a smaller image, remove every package you do not need from the dnf command. If none of the remaining packages use the InfluxData repository, also remove the repository setup and rpm --import command.

Replace the parent tag with any compatible released image for your cluster's Ceph release, Ceph variant, croit release, and processor architecture. Build and publish the image as described above, then add it to croit by reference or use its repository as the cluster's image catalog.

When updating croit, rebuild this image from a compatible image for the new release and publish it under a new tag.

Image requirements

A custom image must keep the following parts of its parent image:

• The io.croit.flags image label. croit uses it to identify the OS, Ceph release, Ceph variant, architecture, and boot support.
• The kernel under /boot and the initramfs at /boot/initrd.img.
• The installed Ceph packages and their configuration.
• The base operating system and boot-time croit integration.

Normal Dockerfile inheritance keeps these parts. Do not replace io.croit.flags, remove boot files, change the kernel, or upgrade and remove Ceph packages. Such changes can make the image incompatible with the cluster even if the registry accepts it.

croit boots the image as a node operating system, not as a container. OCI settings such as CMD, ENTRYPOINT, and container environment variables do not control the booted node. Install files and enable services in the root filesystem instead.

The image's package list is published as metadata. A derived image inherits the parent's package list, so the Packages view may not include packages that your Dockerfile adds.

Do not store registry passwords, license keys, or other secrets in image layers. Use your build tool's secret mechanism and provide runtime secrets through the appropriate croit configuration.

Add one custom image

Use this option when you want to keep croit's image catalog and add one custom image:

1. Open Servers > Images.
2. Select Add Image.
3. Enter the complete registry reference, for example registry.example.com/storage/croit-os:example-agent-v1.
4. Select Add.
5. Follow the Add image from a registry task until the download finishes.

After the task finishes, the custom image appears in the image list and is ready for selection. croit pins the downloaded image to its digest, so moving the registry tag later does not change the files already downloaded.

This workflow keeps croit's image catalog when the image is in a public registry. Private registry credentials are stored with a configured catalog, as described below.

Use a registry as the cluster's image catalog

You can make one repository the source of the cluster's image list:

1. Open Servers > Images > Settings.
2. Open the Registry section.
3. Enter the registry host and repository. For Docker Hub, leave Registry empty and enter the repository, such as my-company/croit-os.
4. Enter a username and password when the registry requires authentication.
5. Enable Plain HTTP only for a trusted internal registry that does not provide HTTPS.
6. Save the settings. croit checks the connection before saving them.

When a repository is configured, it replaces croit's catalog for this cluster. This is also how croit stores credentials for a private image repository. The repository must therefore contain every image the cluster needs, including images for each enabled architecture and images you expect to use for future updates. Leave Repository empty to return to croit's image catalog.

croit lists the repository regularly. Images whose inherited flags match the cluster's Ceph release, variant, and enabled architectures appear in the image list. Published changes are not downloaded to nodes directly. The management node downloads and prepares an image when the cluster needs it.

Updating and rolling back

Publish each revision under a new tag, for example example-agent-v1 and example-agent-v2. Add or select the new image, wait for its download to finish, and then move nodes to it through the normal image change workflow.

Keep the previous image in the registry and on the management node until the new revision has booted successfully on every intended node. To roll back, select the previous image and reboot the affected nodes.

Troubleshooting

If croit cannot add or list an image, check:

• The management node can resolve and connect to the registry host.
• The repository and tag exist.
• The saved credentials can pull from the repository.
• The registry certificate is trusted by the management node.
• The image was published for an enabled processor architecture.
• The image inherits a croit OS image and still carries io.croit.flags.

The task log contains the registry or conversion error for an image added by reference.