SSteady Image CacheGitHub

DOCUMENTATION / GET STARTED

Get SIC running
without surprises.

Use this checklist to prepare the cluster and review the sample configuration. The repository's deployment manifest is a starting point, not a turnkey production installer.

⏱ Setup depends on cluster PKI◇ Kubernetes + containerd

01 / PREPARE

Prerequisites

  • A Kubernetes cluster with containerd on the target nodes.
  • Permission to deploy a DaemonSet, create a TLS Secret, and configure node-level containerd registry hosts.
  • A trusted CA and certificates for SIC peers and containerd clients.
  • A storage location for SIC's independent content cache.
  • A deliberate policy for which clients and registries may access cached content.
Private images need an explicit trust boundary. SIC does not re-authorize each cache read using the original registry credentials. Any client accepted by the SIC listener's client-certificate/access boundary may be able to read content already cached from a private registry. Keep upstream fallback disabled for registries whose content must not be shared across those clients.

02 / SECURITY

Prepare TLS

The sample DaemonSet expects a Secret named steady-image-cache-tls with tls.crt, tls.key, and ca.crt. The certificate must satisfy all three use cases:

  • Peers verify the DNS SAN configured by SIC_TLS_SERVER_NAME (default steady-image-cache).
  • The same SIC certificate is used as a peer client certificate, so it must permit client authentication as well as server authentication.
  • The sample hosts.toml connects to https://127.0.0.1:5000, so the server certificate needs the IP SAN 127.0.0.1.

See the repository's detailed TLS and certificate guide before creating the Secret. Use your organization's PKI for production; do not reuse a throwaway development CA.

03 / CONTAINERD

Configure the registry mirror

Review deploy/containerd/hosts.toml and install it as the appropriate containerd registry host configuration on each node. Adjust certificate paths and registry scope for your environment.

Bootstrap ordering matters. If containerd only tries SIC for a registry, image pulls fail on a node where SIC is not running. The SIC image itself must already be available after node restart or node-image upgrades. Keep imagePullPolicy: IfNotPresent, pin the image to a release tag or digest, and pre-pull/bake it into the node image before installing a mirror configuration that would route SIC's own image back through SIC.

04 / DEPLOY

Configure and deploy the DaemonSet

  1. Review deploy/daemonset.yaml and replace the branch image with a pinned release tag or immutable image digest.
  2. Create the TLS Secret in the namespace used by the manifest.
  3. Choose the cache directory and free-space reserve. Review node disk pressure and eviction thresholds.
  4. Decide whether upstream fallback is needed. It is disabled by default; if enabled, set SIC_UPSTREAM_REGISTRIES to an explicit allow-list.
  5. Apply the manifest only after the containerd mirror and bootstrap path have been planned for your nodes.

Repository checkout

git clone https://github.com/SteadyInfraTech/steady-image-cache.git
cd steady-image-cache
# Review deploy/daemonset.yaml and deploy/containerd/hosts.toml
# Configure TLS, image pinning, and node bootstrap before applying.

Browse deployment files ↗

05 / VERIFY

Verify operation

  • Confirm SIC pods are ready on intended nodes.
  • Check the local health endpoint and Prometheus metrics endpoint through the configured admin listener.
  • Pull an image and verify a second node can reuse content from a peer.
  • Test peer unavailability and upstream-disabled behavior in a controlled environment.
  • Observe cache bytes, eviction, disk-full, corrupt-blob, and stream-abort metrics while testing failures.
  • Confirm the node can recover after SIC pod restart and that the image bootstrap path remains available.

Before production use, exercise the install and recovery flow on a disposable two-node cluster. Follow operations and security guidance for failure cases and metrics.