kimage GitHub
KUBERNETES-NATIVE IMAGE LIFECYCLE

Declare images.
Let the cluster
handle the rest.

Define the image you need. kimage builds it, verifies it, and retains it in a managed local registry, ready for your workloads to run.

Build your first image Explore the source
Open sourceApache 2.0Built in Rust
01 / THE IMAGE IS THE RESOURCE
image.yamlEXAMPLE · EXCERPT 
apiVersion: kimage.dev/v1alpha1
kind: Image
metadata:
  name: service
  namespace: apps
spec:
  version: "1.2.0"
  source:
    build:
      format: Containerfile
      definition:
        inline: |
          FROM scratch
          COPY service /service
          ENTRYPOINT ["/service"]
Desired image Verified release Local registry

Illustrative excerpts. The complete hello example includes input and execution settings.

An image, declared A registry, included A release, retained A normal kubelet pull
DESIRED STATE, ALL THE WAY THROUGH

Your image belongs
in your application’s
declared state.

Apply an Image with a version and production recipe. The controller manages the attempts, verification, and publication needed to make it available.

Compare the approaches
01

Declare the outcome

The Image is the durable resource. Build attempts are execution details managed by the controller, with retries and recovery.

02

Keep publication close

A PVC-backed OCI registry is part of the installation. Application images need no separate output registry URL or push credentials. External export is optional.

03

Give releases their own lifetime

Verified releases remain available after input objects are removed or builder caches are cleared. A published version cannot be replaced with different content.

A CLEAR PATH FROM SPEC TO POD

Four steps.
One image lifecycle.

Production, retention, and consumption share a Kubernetes API. Each component has a distinct job.

  1. 01 / DECLARE

    Describe the image

    Choose a version, local inputs, a Containerfile, and the default builder.

    Image
  2. 02 / PRODUCE

    Build and verify

    Pinned BuildKit produces OCI content. Verification checks its graph and bytes.

    BuildKit → OCI
  3. 03 / RETAIN

    Publish a release

    Retain the content in cluster-local storage and record the immutable result.

    ImageRelease
  4. 04 / CONSUME

    Run your workload

    Admission pins the selected release. Kubelet pulls through a node-local read proxy.

    Pod → digest
VERSION SELECTION THAT READS WELL

A name you recognize.
A digest you can trust.

Use exact versions for uniform rollouts, ranges for compatible releases, or a channel you explicitly map. Each new Pod gets a concrete digest.

Selectors resolve at Pod creation. Publishing a release does not restart existing workloads. Consumption is currently restricted to the same namespace.

EXACT VERSIONplatform://apps/service:1.2.4
COMPATIBLE RANGEplatform://apps/service:^1.2.0Readable query ranges work too.
EXPLICIT CHANNELplatform://apps/service:stable
YOUR FIRST IMAGE

Start small.
See the whole path.

Install the native CLI with Cargo or choose Helm. Kubernetes pulls component images from GHCR, without a source checkout or packaging script. The hello tutorial takes a static executable through a scratch build, a retained release, and a running Deployment.

1

Prepare a development cluster

Pull pinned native release images, then install the control plane and default builder using the handbook.

2

Apply the hello Image

Provide the small executable in a ConfigMap. The controller builds and publishes version 1.0.0.

3

Run it by name

Apply the Deployment and inspect the resulting digest-pinned Pod image.

Follow the full tutorial
INSTALL THE NATIVE CLI 
# Rust 1.99.0
$ cargo install kimage-control \
    --version 0.4.0 --locked --bin kimage --bin kimage-install
$ kimage install --application-namespace apps

# After preparing the tutorial inputs
$ kubectl apply -f examples/hello/image.yaml
$ kubectl apply -f examples/hello/deployment.yaml
$ kubectl -n apps wait \
    --for=condition=Ready image/hello
An image declaration. A running workload.
ALPHA

A focused baseline, with explicit boundaries.

Native amd64 and arm64 builds, on-demand or eager, with namespace or cluster scope. Current builds use scratch images and provisioned local inputs. Runtime versions are checked at installation.

Read compatibility and limits
Native macOS + Linux installers63 tests on macOS + Linux/muslTwo-node live acceptance evidence

Your images.
Part of your cluster.

Explore the code, try the tutorial, or help shape what comes next.

Find kimage on GitHub Join the discussion