Project 2: OCI Image Builder and Registry Workflow

Build an educational OCI artifact workflow that produces layer digests, manifest metadata, and registry push/pull verification.

Quick Reference

Attribute Value
Difficulty Advanced
Time Estimate 10-16 hours
Main Programming Language Go (Alternatives: Rust, Python)
Alternative Programming Languages Rust, Python
Coolness Level Level 3 - Genuinely Clever
Business Potential 3. Platform Service
Prerequisites OCI basics, JSON schemas, HTTP workflows
Key Topics manifests, layers, digests, tag drift, promotion safety

1. Learning Objectives

  1. Explain OCI image and distribution model clearly.
  2. Build digest-first release flow with deterministic verification.
  3. Diagnose registry push/pull failures by protocol stage.
  4. Design artifact promotion strategy for production safety.

2. All Theory Needed (Per-Concept Breakdown)

2.1 OCI Artifact Graph

Fundamentals

OCI image artifacts are immutable objects connected by digests. Layers represent filesystem changes, config carries runtime defaults, and manifest references both. Tags are mutable aliases, not immutable identity.

Deep Dive into the concept

A reliable deployment pipeline depends on digest truth. Tags are useful human labels but can move over time, causing drift between what was tested and what is running. Digests remove this ambiguity. Layer deduplication allows registries to reuse content across images, reducing bandwidth and storage costs. Understanding media types, descriptor sets, and platform-specific manifests is essential when supporting multi-architecture workloads.

How this fit on projects

  • Core for P02, reused in P03 and P10.

Definitions & key terms

  • Descriptor, manifest list, config object, content-addressable storage.

Mental model diagram

tag -> manifest digest -> [config digest + layer digests]

How it works

  1. Build layers and config.
  2. Create manifest referencing those blobs.
  3. Push blobs and manifest.
  4. Resolve tags to manifest digests.

Invariants: digest immutability. Failure modes: tag drift, digest mismatch, media type incompatibility.

Minimal concrete example

tag app:prod -> sha256:AAA
deploy image@sha256:AAA

Common misconceptions

  • “Tag is enough for production traceability.” -> false.

Check-your-understanding questions

  1. Why deploy by digest?
  2. Why does layer ordering affect cache behavior?

Check-your-understanding answers

  1. Prevents mutable-tag drift.
  2. Cache hits depend on unchanged dependency chain.

Real-world applications

  • Artifact promotion pipelines, compliance evidence.

Where you’ll apply it

  • P02, P03, P10.

References

  • OCI image/distribution release notices
  • Docker registry docs

Key insights

  • Digest identity is the anchor of reproducible delivery.

Summary

  • OCI model literacy is mandatory for reliable platform pipelines.

Homework/Exercises to practice the concept

  1. Map one build output to full digest graph.
  2. Simulate tag drift and detect it.

Solutions to the homework/exercises

  1. Generate manifest and record all child descriptors.
  2. Compare deployed digest against expected release metadata.

2.2 Registry Push/Pull Protocol Stages

Fundamentals

Registry interactions are staged protocol flows with auth, blob checks, uploads, manifest publish, and tag update.

Deep Dive into the concept

Most failures happen at predictable points: auth scope mismatch, missing upload session completion, manifest schema mismatch, or pull authorization errors. Explicit stage-level logging reduces mean time to resolution. Retry strategy should differentiate between transient network errors and deterministic protocol errors.

How this fit on projects

  • P02 primary, P04 incident diagnostics, P10 release orchestration.

Definitions & key terms

  • blob upload session, auth scope, manifest media type.

Mental model diagram

auth -> check blob exists -> upload missing blob -> publish manifest -> update tag

How it works

  1. Request token.
  2. Query blob existence.
  3. Upload missing blobs.
  4. Publish manifest.
  5. Pull and verify digest.

Invariants: manifest references must resolve. Failure modes: unauthorized scope, unknown blob, unsupported manifest type.

Minimal concrete example

if blob exists: skip upload
else: upload and verify digest

Common misconceptions

  • “Push is one API call.” -> it is a multi-stage transaction.

Check-your-understanding questions

  1. Why can manifest upload fail after blob upload success?
  2. Why should retries be stage-aware?

Check-your-understanding answers

  1. Schema/media type or auth mismatch on manifest endpoint.
  2. Some failures are permanent and should not be blindly retried.

Real-world applications

  • CI reliability and release governance.

Where you’ll apply it

  • P02, P04, P10.

References

  • OCI distribution spec

Key insights

  • Stage-aware diagnostics turn registry incidents into routine fixes.

Summary

  • Protocol literacy beats retry loops.

Homework/Exercises to practice the concept

  1. Build a stage-by-stage failure taxonomy.
  2. Add actionable error messaging per stage.

Solutions to the homework/exercises

  1. Classify by auth, transport, schema, and integrity.
  2. Include remediation hints tied to each class.

3. Project Specification

3.1 What You Will Build

A CLI workflow that:

  • builds OCI-style artifact metadata
  • pushes to registry with stage logs
  • pulls by digest and verifies integrity

3.2 Functional Requirements

  1. Generate manifest/config/layer descriptors.
  2. Support digest verification after pull.
  3. Emit stage-level logs and structured errors.
  4. Export promotion metadata for downstream deploy.

3.3 Non-Functional Requirements

  • Performance: warm push path avoids re-uploading existing blobs.
  • Reliability: deterministic failure classification.
  • Usability: one command for build+push+verify mode.

3.4 Example Usage / Output

$ ./oci-lab build ./app
$ ./oci-lab push registry.local/app:lab
$ ./oci-lab verify registry.local/app@sha256:...

3.5 Data Formats / Schemas / Protocols

  • Manifest descriptor set
  • Push stage event schema
  • Promotion metadata: environment, digest, timestamp

3.6 Edge Cases

  • Registry already has all layers.
  • Tag exists and points to different digest.
  • Pull succeeds but digest verification fails.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ ./oci-lab build ./demo
$ ./oci-lab push registry.local/demo:lab
$ ./oci-lab pull registry.local/demo@sha256:9f9e...

3.7.2 Golden Path Demo (Deterministic)

  • Build from known source snapshot.
  • Push once (uploads all blobs), push again (uploads none).
  • Pull by digest and verify equality.

3.7.3 If CLI: exact terminal transcript

$ ./oci-lab push registry.local/demo:lab
[STAGE] auth OK
[STAGE] blob check: 2/2 exists
[STAGE] manifest publish OK sha256:9f9e...
[STAGE] tag update OK demo:lab -> sha256:9f9e...

$ ./oci-lab verify registry.local/demo@sha256:9f9e...
[VERIFY] digest match
[VERIFY] manifest descriptor count: 3

4. Solution Architecture

4.1 High-Level Design

builder -> artifact graph -> registry client -> verification engine -> promotion metadata

4.2 Key Components

Component Responsibility Key Decisions
Artifact builder create descriptors digest-first design
Registry client push/pull stages stage-aware error model
Verifier integrity checks immutable digest enforcement
Reporter promotion records traceability for deploys

4.4 Data Structures (No Full Code)

ManifestDescriptor:
- digest
- media_type
- size

PushStageEvent:
- stage
- status
- error_class

4.4 Algorithm Overview

  1. Build artifact graph.
  2. Push missing blobs and manifest.
  3. Pull by digest.
  4. Verify and emit promotion record.

5. Implementation Guide

5.1 Development Environment Setup

# local registry + jq + docker tooling

5.2 Project Structure

oci-lab/
  cmd/
  internal/artifacts/
  internal/registry/
  internal/verify/

5.3 The Core Question You’re Answering

“How do we prove artifact integrity end-to-end across build, registry, and deployment steps?”

5.4 Concepts You Must Understand First

  • OCI manifest model
  • digest vs tag semantics
  • registry auth and stage flows

5.5 Questions to Guide Your Design

  1. Which operations require immutable references?
  2. How will operators diagnose failures from one log line?

5.6 Milestones

  1. Artifact graph generation.
  2. Push pipeline with stage logs.
  3. Pull+verify flow.
  4. Promotion metadata export.

5.7 Validation and Testing

  • success path tests
  • auth failure tests
  • digest mismatch tests

5.8 Common Pitfalls and Recovery

  • mutable tag deployments
  • non-actionable registry errors

5.9 Definition of Done

  • Digest verification workflow complete.
  • Stage-level diagnostics implemented.
  • Promotion metadata produced.
  • Failure taxonomy documented.