Chainguard Container for image-factory

Image Factory is a flexible artifact-build service for Talos Linux, offering automated creation of ISOs, disks, cloud images, and installers and ensuring reproductible builds.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/image-factory:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

This image is based on the upstream image-factory image. Key differences from the standard image-factory image:

• Cross-architecture builds are not supported. Unlike the upstream image, this variant cannot build ARM images on AMD containers or AMD images on ARM containers.
• ISO generation is unavailable when using the ARM version of the image.

Prerequisites

To run the Image Factory container successfully, the host environment must provide the following (a single registry can be used for 1-3):

1. an OCI registry to store schematics (private)
2. an OCI registry to store cached assets (private)
3. an OCI registry to store installer images (should allow public read-only access)
4. a container image signing key: ECDSA P-256 private key in PEM format
5. partitionable loop devices: the container needs access to loop devices that support partitions.

More details regarding the setup can be found here.

Getting Started

Image Factory can be deployed either as a standalone container or inside a Kubernetes cluster. This section provides minimal examples to help you start the service using the supported deployment methods. These examples assume you have already set up the prerequisites (registry, signing key, and partitionable loop devices).

Running with Docker

You can run Image Factory directly as a container. Example:

docker run -d --rm --name image-factory \
  -p 8080:8080 \
  --privileged \
  -v /dev:/dev \
  -v $PWD/cache-signing-key.key:/cache-signing-key.key:ro \
  cgr.dev/ORGANIZATION/image-factory \
  -image-registry ghcr.io \
  -external-url http://localhost:8080 \
  -schematic-service-repository <SCHEMATIC-REGISTRY-IP>:<SCHEMATIC-REGISTRY-PORT>/image-factory/schematic \
  -installer-internal-repository <INSTALLER-REGISTRY-IP>:<INSTALLER-REGISTRY-PORT>/siderolabs \
  -installer-external-repository <INSTALLER-REGISTRY-IP>:<INSTALLER-REGISTRY-PORT>/siderolabs \
  -cache-repository <CACHE-REGISTRY-IP>:<CACHE-REGISTRY-PORT>/cache \
  -cache-signing-key-path /cache-signing-key.key \

After the container starts, the Image Factory API is available on http://localhost:8080 . You can now submit build requests using the API or CLI tools that interact with Image Factory. Example:

cat > "metal-amd64.yaml" <<'EOF'
customization:
    extraKernelArgs: # optional
        - vga=791
    meta: # optional, allows to set initial Talos META
      - key: 0xa
        value: "{}"
    systemExtensions: # optional
      officialExtensions: # optional
        - siderolabs/gvisor
        - siderolabs/amd-ucode
    secureboot: # optional, only applies to SecureBoot images
       # optional, include well-known UEFI certificates into auto-enrollment database (SecureBoot ISO only)
      includeWellKnownCertificates: true
overlay: # optional
  image: ghcr.io/siderolabs/sbc-raspberry-pi # overlay image
  name: rpi_generic # overlay name
  options: # optional, any valid yaml, depends on the overlay implementation
    data: "mydata"
EOF

SCHEMATIC_ID=$(curl -fsSL -X POST --data-binary @"./metal-amd64.yaml" "http://localhost:8080/schematics" | jq -r '.id')
# Download raw image
curl -o "./metal-amd64.raw.zst" "http://localhost:8080/image/${SCHEMATIC_ID}/v1.11.5/metal-amd64.raw.zst"

Running in Kubernetes

Image Factory can be deployed using a simple Kubernetes manifest. Example:

cat > "image-factory.yaml" <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: image-factory
  namespace: image-factory
  labels:
    app: image-factory
spec:
  replicas: 1
  selector:
    matchLabels:
      app: image-factory
  template:
    metadata:
      labels:
        app: image-factory
    spec:
      containers:
        - name: image-factory
          image: cgr.dev/ORGANIZATION/image-factory
          securityContext:
            privileged: true
          args:
            - -image-registry
            - ghcr.io

            - -external-url
            - http://<NODE_IP>:30080

            - -schematic-service-repository
            - <SCHEMATIC-REGISTRY-IP>:<SCHEMATIC-REGISTRY-PORT>/image-factory/schematic

            - -installer-internal-repository
            - <INSTALLER-REGISTRY-IP>:<INSTALLER-REGISTRY-PORT>/siderolabs

            - -installer-external-repository
            - <INSTALLER-REGISTRY-IP>:<INSTALLER-REGISTRY-PORT>/siderolabs

            - -cache-repository
            - <CACHE-REGISTRY-IP>:<CACHE-REGISTRY-PORT>/cache

            - -cache-signing-key-path
            - /cache-signing-key.key
          ports:
            - containerPort: 8080
              name: http
          volumeMounts:
            - name: dev
              mountPath: /dev
            - name: cache-signing-key
              mountPath: /cache-signing-key.key
              subPath: cache-signing-key.key
              readOnly: true
      volumes:
        - name: dev
          hostPath:
            path: /dev
            type: Directory
        - name: cache-signing-key
          secret:
            secretName: cache-signing-key
---
apiVersion: v1
kind: Service
metadata:
  name: image-factory
  namespace: image-factory
  labels:
    app: image-factory
spec:
  selector:
    app: image-factory
  type: NodePort
  ports:
    - name: http
      port: 8080
      targetPort: 8080
      nodePort: 30080
EOF

cat > "metal-amd64.yaml" <<'EOF'
customization:
    extraKernelArgs: # optional
        - vga=791
    meta: # optional, allows to set initial Talos META
      - key: 0xa
        value: "{}"
    systemExtensions: # optional
      officialExtensions: # optional
        - siderolabs/gvisor
        - siderolabs/amd-ucode
    secureboot: # optional, only applies to SecureBoot images
       # optional, include well-known UEFI certificates into auto-enrollment database (SecureBoot ISO only)
      includeWellKnownCertificates: true
overlay: # optional
  image: ghcr.io/siderolabs/sbc-raspberry-pi # overlay image
  name: rpi_generic # overlay name
  options: # optional, any valid yaml, depends on the overlay implementation
    data: "mydata"
EOF

kubectl apply -f image-factory.yaml
node_ip=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
factory_url="http://${node_ip}:30080"

# You can now interact with the image-factor API via nodeport service
SCHEMATIC_ID=$(curl -fsSL -X POST --data-binary @"./metal-amd64.yaml" "${factory_url}/schematics" | jq -r '.id')
# Download raw image
curl -o "./metal-amd64.raw.zst" "${factory_url}/image/${SCHEMATIC_ID}/v1.11.5/metal-amd64.raw.zst"

Documentation and Resources

For more information about Image-Factory in container images, please refer to the official documentation or to the official repository.

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.