Skip to content

Architecture

0. Document intent and versioning

This document describes v2.0.0 of our OpenStack image CI/CD architecture.
It is intentionally scoped to the current baseline and does not attempt to cover future features (e.g., automated promotions, signing, SBOM enforcement, full upstream gating parity). Those will be added in subsequent versions.

1. Goal

Build OpenStack 2024.1 container images (Kolla) in a fully air-gapped environment using offline-delivered artifacts, with build execution orchestrated by Zuul and triggered manually.

2. Environments

graph TB
    subgraph "External World"
        Upstream[Upstream Sources<br/>OpenStack/Pypi/Docker Hub]
    end

    subgraph "Environment A: Mirror Factory (Connected)"
        direction TB
        FW[Configurable Firewall<br/>Controlled Access]
        AuthA[Gerrit + Zuul<br/>Validation Workflows]
        NexusA[Nexus Repository<br/>Central Artifact Storage]

        Upstream -- "Updates (Only during refresh)" --> FW
        FW --> NexusA
        AuthA -.-> NexusA
    end

    subgraph "The Air Gap"
        Media[Offline Deliverable<br/>Artifact Bundle]
    end

    subgraph "Environment B: Build Environment (Disconnected)"
        direction TB
        AuthB[Gerrit<br/>Code Review/Source]
        OrchB[Zuul<br/>Build Orchestration]
        RepoB[Artifacts Nexus<br/>Imported Dependencies]
        RegB[Images Nexus<br/>Docker Registry]

        Operator((Operator)) -- "Manual Trigger" --> OrchB
        OrchB -- "Reads Source" --> AuthB
        OrchB -- "Pulls Dependencies" --> RepoB
        OrchB -- "Publishes Images" --> RegB
    end

    NexusA -- "Generate Bundle" --> Media
    Media -- "Import Bundle" --> RepoB
    Media -- "Import Base Images" --> RegB

    style FW fill:#f9f,stroke:#333,stroke-width:2px
    style Media fill:#ff9,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    style Operator fill:#fff,stroke:#333

2.1 Environment A — Mirror Factory (Connected)

Purpose: Prepare and curate all artifacts required to build OpenStack 2024.1 images, using controlled internet access.

Components

  • Gerrit + Zuul (+ supporting services): used to run internal jobs/playbooks that prepare and validate artifact sets (manual/controlled workflows).
  • Nexus: central artifact repository (raw/apt/pypi/docker as applicable).
  • Configurable firewall: enables tightly controlled internet access (open only during updates; closed otherwise).

Duty (v2.0.0)

  • Manual preparation of the artifacts needed to build 2024.1 images:
    • Source tarballs required by Kolla/OpenStack builds
    • Third-party binaries (arch-aware)
    • OS packages (mirror/proxy strategy)
    • Python packages (proxy cache/hosted as required)
    • Base container images (cached/mirrored)
  • Produce an offline-deliverable artifact bundle (plus manifest/checksums) per update.

2.2 Environment B — Air-Gapped Build Environment (Disconnected)

Purpose: Build OpenStack 2024.1 images using only offline-delivered artifacts, without any internet access.

Components

  • Gerrit: authoritative code review and repository source for the build.
  • Zuul (+ supporting services): orchestrates build job execution.
  • Artifacts Nexus: Nexus instance (or Nexus repositories) containing imported artifacts from the Mirror Factory bundle.
  • Images Nexus: Nexus-hosted Docker registry (or dedicated Nexus Docker repos) used to store built images (staging/release tags).

Duty (v2.0.0)

  • Build 2024.1 images using Kolla, strictly from offline delivered artifacts.
  • Execute builds via manual trigger of Zuul jobs.

3. End-to-end process (v2.0.0)

sequenceDiagram
    autonumber
    participant Upstream as Upstream Sources
    participant Factory as Env A: Mirror Factory
    participant Media as Offline Media
    participant AirGap as Env B: Air-Gapped
    participant Registry as Images Nexus (Env B)

    Note over Upstream, Factory: 1. Upstream Update Detected

    Factory->>Upstream: Refresh Mirrors & Caches
    Factory->>Factory: Validate Artifact Completeness
    Factory->>Media: Generate Artifact Bundle

    Note right of Factory: Includes tarballs, binaries,<br/>OS packages, PyPi, Base Images [2]

    Media->>AirGap: 3. Offline Delivery (Integrity Checks)

    AirGap->>AirGap: 4. Import Artifacts to Nexus
    AirGap->>Registry: Import Base Images

    actor Ops as Operator
    Ops->>AirGap: 5. Manually Trigger Zuul Job

    Note right of AirGap: Build OpenStack 2024.1 Kolla Images<br/>using ONLY offline artifacts [3]

    AirGap->>Registry: 6. Publish Built Images
    AirGap->>AirGap: Retain Build Logs/Artifacts
  1. Upstream update detected (new commits / new pinned dependencies / planned refresh window).
  2. In Mirror Factory, operators:
    • refresh mirrors/caches into Nexus and image cache
    • validate completeness
    • generate an artifact bundle (versioned) for offline delivery
  3. Offline deliver the bundle to the Air-Gapped environment (approved media + integrity checks).
  4. In Air-Gapped, operators:
    • import artifacts into Artifacts Nexus
    • import base images into Images Nexus (as needed)
  5. Operators manually trigger the Zuul build job to build OpenStack 2024.1 Kolla images.
  6. Images are published into Images Nexus and build artifacts/logs are retained internally.

4. Non-goals (explicitly out of scope for v2.0.0)

  • Fully automated upstream polling and artifact regeneration
  • Automated promotion pipelines (staging → prod) with approvals
  • Signing/verification enforcement across all artifacts and images
  • Full parity with upstream OpenDev gating
  • Automated SBOM/provenance enforcement (may be added later)

5. Success criteria (v2.0.0)

  • Air-gapped builds complete with zero internet access
  • All build inputs are satisfied via offline-delivered artifacts
  • Builds are repeatable given the same artifact bundle and Git refs
  • Manual trigger path is reliable and auditable