How kubernetes-sigs/promo-tools works
Project Type and Purpose
• This is a command-line suite of tools (written in Go) for promoting artifacts (container images, files, GitHub releases) in the Kubernetes release process.
• It packages multiple subcommands (kpromo, cip, cip-mm, cip-auditor, gh2gcs, etc.) that share common libraries.
File Structure
Top-level directories and purposes:
• cmd/… – each subfolder is a CLI entrypoint (e.g. kpromo, count-requests, verify-gcr-quota).
• internal/… & api/… – core libraries for interacting with registries, GCP, GitHub, streaming, auditing.
• promoter/… & image/…, promobot/… – higher-level modules for file- and image-promotion logic.
• canary/… – manifests and images used for pre-production “canary” promotions.
• test-e2e/… – end-to-end test harness and fixtures.
• docs/, Dockerfile, cloudbuild.yaml, Makefile – operational and build tooling.
README Insights
• The kpromo binary unifies several legacy tools (cip, cip-mm, cip-auditor, gh2gcs, etc.) into subcommands.
• Promotion workflows cover image staging→production, file uploads to GCS/S3, and GitHub release uploads.
Main Components & Relationships
a. CLI Layer (cmd/*)
• kpromo (root) → subcommands: cip, manifest, pr, run, gh, etc.
• Other direct entrypoints: cip-mm, count-requests, verify-gcr-quota.
• Pattern: uses Cobra for command dispatch (root.go, cmd/*.go).
b. Core Libraries
• promoter/file – interfaces & implementations for file stores (GCS, S3, local).
• promoter/image – orchestrates image promotion: security scans, signing, snapshotting.
• api/files – manifest generation/validation for files.
• internal/dockerregistry – reading/writing image registry metadata.
• internal/gcloud, internal/logclient – GCP token handling & logging.
• internal/stream – HTTP/subprocess streams for running external commands.
c. Legacy Wrappers
• internal/legacy – older versions of CIP, audit, registry logic. Wrapped by new tools for backward compatibility.
d. Test Harness
• test-e2e containers & fixtures for CIP and auditor subcommands.
e. External Services
• Container registries (staging & production)
• Google Cloud Storage (GCS)
• S3 (optional file store)
• GitHub API & releases
• Google Cloud Build (cloudbuild.yaml)
Architectural Patterns & Principles
• Layered structure: CLI → orchestration libraries → transport/adapters → external services.
• Interface-based design: promoter/file and promoter/image define interfaces and pluggable implementations.
• Command pattern: each subcommand implements a discrete promotion flow.
• Backward-compatibility: legacy code under internal/legacy coexists with new modules.