Image Factory Exemplar

A minimal, self-contained example of the Image Factory system using a simple nginx application.

Purpose

• Learning Resource: Understand Image Factory with a simple example
• Testing Environment: Validate functionality without production dependencies
• Template: Starting point for your own Image Factory setup

Structure

image-factory-exemplar/
├── image-factory/          # Submodule: Image Factory code
├── images.yaml            # Image enrollment registry (manually managed)
├── base-images/           # Generated state files for base images (committed)
├── images/                # Generated state files for application images (committed)
├── dist/                  # Generated artifacts (committed)
│   └── cdk8s/            # Kargo manifests from CDK8s synthesis
├── app/                   # Example nginx application
│   ├── Dockerfile
│   └── index.html
└── .gitignore             # Ignores submodule build artifacts

Manually Managed:

• images.yaml - Image enrollment registry
• app/ - Example application code

Generated & Committed:

• base-images/ - State files generated by Image Factory tool
• images/ - State files generated by Image Factory tool
• dist/cdk8s/ - Kargo manifests generated by CDK8s synthesis

These generated files are committed to git so ArgoCD can deploy them.

Quick Start

Production Setup

# Clone with submodules
git clone --recursive https://github.com/craigedmunds/image-factory-exemplar.git
cd image-factory-exemplar

Local Development Setup

When developing locally with both repos checked out:

# From workspace-root/repos/
cd image-factory-exemplar
ln -s ../image-factory image-factory

This creates a symlink to the local image-factory repo for easier development.

Manual Workflow (Without Kargo)

The Image Factory normally runs automatically via Kargo, but you can run each step manually for testing and development:

Local vs External Dockerfiles

This exemplar repo has local Dockerfiles (in app/Dockerfile), so base image discovery happens during task generate.

The production image-factory-state repo has external Dockerfiles (in other repos like craigedmunds/argocd-eda). For those:

• task generate creates initial state files without base image discovery
• Base image discovery happens later in Kargo’s AnalysisRun when it clones the source repos

1. Setup

# Set up Python environments for app and cdk8s
task setup

2. Generate State Files

# Generate base-images/ and images/ from images.yaml
task generate

This runs the Image Factory app tool to create state files.

3. Synthesize Manifests

# Generate dist/cdk8s/image-factory.k8s.yaml from state files
task synth

This runs CDK8s to generate Kargo Warehouses, Stages, and AnalysisTemplates.

4. Build Image (Optional)

# Build the Docker image locally
task build

This is normally done by Kargo Warehouse.

5. Deploy (Optional)

# Deploy the generated manifests to Kubernetes
task deploy

This is normally done by ArgoCD watching the state repo at dist/cdk8s/.

Complete Manual Workflow

# Full workflow from images.yaml to deployed manifests
task setup      # One-time setup
task generate   # Generate state files
task synth      # Generate Kargo manifests
task status     # Check what was generated

Related Repositories

• image-factory - Code (submodule)
• image-factory-state - Production config