# kubernetes-sigs/promo-tools architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/promo-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/promo-tools
- Repository: https://github.com/kubernetes-sigs/promo-tools

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        kpromo["kpromo"]:::cli
        cipmm["cip-mm"]:::cli
        countreq["count-requests"]:::cli
        verifygcr["verify-gcr-quota"]:::cli
        gh2gcs["gh2gcs"]:::cli
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        filepromo["promoter/file\n(FileStore interface)"]:::orchestration
        imagepromo["promoter/image\n(ImagePromoter interface)"]:::orchestration
        apifiles["api/files\n(ManifestGenerator/Validator)"]:::orchestration
        promobot["promobot"]:::orchestration
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        dockerreg["internal/dockerregistry"]:::adapter
        gcloudlog["internal/gcloud & logclient"]:::adapter
        stream["internal/stream"]:::adapter
        legacy["internal/legacy"]:::adapter
    end

    %% External Services
    subgraph "External Services"
        direction TB
        registry[(Docker Registry\nstaging & prod)]:::external
        gcs[(GCS Bucket)]:::external
        s3[(S3 Bucket)]:::external
        github[(GitHub API)]:::external
        cloudbuild[(Cloud Build)]:::external
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        e2ecip["test-e2e/cip"]:::test
        e2eaudit["test-e2e/cip-auditor"]:::test
    end

    %% Connections: CLI -> Orchestration
    kpromo -->|uses| filepromo
    kpromo -->|uses| imagepromo
    kpromo -->|uses| apifiles
    cipmm -->|uses| filepromo
    countreq -->|uses| apifiles
    verifygcr -->|uses| apifiles
    gh2gcs -->|uses| filepromo

    %% Orchestration -> Adapter
    filepromo -->|reads/writes| gcloudlog
    filepromo -->|streams| stream
    filepromo -->|fallback| legacy
    imagepromo -->|push/pull| dockerreg
    imagepromo -->|streams| stream
    apifiles -->|streams| stream
    promobot -->|orchestrates| filepromo
    promobot -->|orchestrates| imagepromo

    %% Adapter -> External
    dockerreg -->|push/pull image| registry
    gcloudlog -->|auth/logging| gcs
    gcloudlog -->|auth/logging| cloudbuild
    stream -->|HTTP/SUBPROCESS| registry
    legacy -->|legacy flows| registry
    legacy -->|legacy flows| gcs
    legacy -->|legacy flows| github

    %% Orchestration -> External
    apifiles -->|upload file| gcs
    apifiles -->|upload file| s3
    apifiles -->|create release| github

    %% Test Harness connections
    e2ecip -->|invokes CLI| kpromo
    e2ecip -->|fixtures| registry
    e2ecip -->|fixtures| gcs
    e2eaudit -->|invokes CLI| kpromo
    e2eaudit -->|fixtures| registry
    e2eaudit -->|fixtures| gcs

    %% CI/CD Integration
    cloudbuild -->|builds binaries| kpromo

    %% Click Events
    click kpromo "https://github.com/kubernetes-sigs/promo-tools/blob/main/cmd/kpromo/main.go"
    click kpromo "https://github.com/kubernetes-sigs/promo-tools/blob/main/cmd/kpromo/cmd/root.go"
    click cipmm "https://github.com/kubernetes-sigs/promo-tools/blob/main/cmd/cip-mm/README.md"
    click cipmm "https://github.com/kubernetes-sigs/promo-tools/tree/main/cmd/cip-mm/"
    click countreq "https://github.com/kubernetes-sigs/promo-tools/blob/main/cmd/count-requests/main.go"
    click verifygcr "https://github.com/kubernetes-sigs/promo-tools/blob/main/cmd/verify-gcr-quota/main.go"
    click gh2gcs "https://github.com/kubernetes-sigs/promo-tools/blob/main/gh2gcs/gh2gcs.go"
    click filepromo "https://github.com/kubernetes-sigs/promo-tools/tree/main/promoter/file/"
    click imagepromo "https://github.com/kubernetes-sigs/promo-tools/blob/main/promoter/image/promoter.go"
    click apifiles "https://github.com/kubernetes-sigs/promo-tools/blob/main/api/files/manifest.go"
    click apifiles "https://github.com/kubernetes-sigs/promo-tools/blob/main/api/files/validation.go"
    click promobot "https://github.com/kubernetes-sigs/promo-tools/blob/main/promobot/promotefiles.go"
    click promobot "https://github.com/kubernetes-sigs/promo-tools/blob/main/promobot/hash.go"
    click dockerreg "https://github.com/kubernetes-sigs/promo-tools/tree/main/internal/legacy/dockerregistry/"
    click gcloudlog "https://github.com/kubernetes-sigs/promo-tools/blob/main/internal/legacy/gcloud/token.go"
    click gcloudlog "https://github.com/kubernetes-sigs/promo-tools/blob/main/internal/legacy/logclient/gcp.go"
    click stream "https://github.com/kubernetes-sigs/promo-tools/blob/main/internal/legacy/stream/http.go"
    click legacy "https://github.com/kubernetes-sigs/promo-tools/blob/main/internal/legacy/cli/root.go"
    click legacy "https://github.com/kubernetes-sigs/promo-tools/blob/main/internal/legacy/audit/auditor.go"
    click e2ecip "https://github.com/kubernetes-sigs/promo-tools/tree/main/test-e2e/cip/"
    click e2eaudit "https://github.com/kubernetes-sigs/promo-tools/tree/main/test-e2e/cip-auditor/"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef orchestration fill:#DFFFE0,stroke:#237804,color:#237804,stroke-width:1px;
    classDef adapter fill:#FFF3CD,stroke:#D48806,color:#D48806,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6C757D,color:#6C757D,stroke-width:1px,stroke-dasharray: 5 5;
    classDef test fill:#F5E6FF,stroke:#9B59B6,color:#9B59B6,stroke-width:1px;
```
