Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions AIRGAP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Airgap / Disconnected Patterns

This page summarizes Patternizer’s disconnected (airgap) workflow. For the full walkthrough and lab notes, see the [Disconnected Patterns UX Update](https://validatedpatterns.io/blog/2026-10-26-disconnected-updates/) blog post. For general disconnected install guidance, see the [disconnected installation guide](https://validatedpatterns.io/learn/disconnected-installation/).

- [Airgap / Disconnected Patterns](#airgap--disconnected-patterns)
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Example Workflow](#example-workflow)
- [Usage Details](#usage-details)
- [Collect artifacts (`airgap init`)](#collect-artifacts-airgap-init)
- [Move content into the airgap](#move-content-into-the-airgap)
- [Prepare the pattern](#prepare-the-pattern)
- [Configure secrets and bootstrap](#configure-secrets-and-bootstrap)
- [Install](#install)
- [Further reading](#further-reading)

## Overview

Identifying every operator, container image, and Helm chart for a pattern is tedious—especially when remote charts use wildcard versions. Patternizer’s airgap commands scrape a pattern repository for those artifacts, merge optional extras from a config file, and generate an oc-mirror v2 `imagesetconfig.yaml` plus helpers for disconnected install.

The same tooling can include operators, images, and charts for workflows that are not pattern-specific via `--extra-config`.

## Quick Start

**Prerequisites:**

- Podman or Docker (or a local Patternizer binary)
- A pattern repository (local path or Git URL)
- Access to a connected machine for mirroring, then a bastion in the airgap

```bash
# Optional shell helper (see README for the full function)
patternizer airgap init https://github.com/validatedpatterns/multicloud-gitops \
--extra-config "$HOME/extra-images.yaml" \
--ocp-version 4.22 \
--output-dir "$HOME/mcgodemo"
```

## Example Workflow

Using [multicloud-gitops](https://github.com/validatedpatterns/multicloud-gitops) as the example pattern:

1. **On a connected host:** run `patternizer airgap init` to scrape the pattern, merge `--extra-config`, and write outputs under `--output-dir`.
2. **Mirror** images into your disconnected registry with oc-mirror (use generated `mirror-commands.sh`). Install OpenShift in the airgap if needed.
3. **Copy** the `--output-dir` tree to the bastion (`scp -r …`).
4. **Publish** the cloned pattern into your airgapped Git service (for example Gitea).
5. **On the bastion:** `patternizer upgrade`, configure `~/values-secret-<pattern>.yaml` with an `airgap:` section, run `patternizer airgap bootstrap`, commit/push, then `./pattern.sh make install-airgap`.

## Usage Details

### Collect artifacts (`airgap init`)

Patternizer scrapes the repository for operators, container images, and Helm charts. Path-based charts (`path: charts/...`) contribute images under `additionalImages`. Remote OCI charts (`chart:` / `chartVersion:`) are resolved (wildcards take the latest) and scanned. Git clones use full history to avoid shallow-clone issues when pushing into your Git service.

| Flag | Purpose |
|------|---------|
| `--extra-config` | YAML merge of extra operators, `additionalImages`, and `helm.local` |
| `--ocp-version` | Include OpenShift platform channel `stable-<version>` and tag OLM catalogs / CatalogSources (default catalog tag `4.22` when omitted) |
| `--output-dir` | Generated artifacts (default `./airgap-out`) |
| `--registry` | Optional mirror hostname for `values-disconnected.yaml` / `mirror-commands.sh` |
| `--download-oc-mirror` | Download oc-mirror archives into `--output-dir` |
| `--git-ref` / `--clone-dir` | Git branch/tag and clone location when source is a URL |

Example `--extra-config`:

```yaml
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.22
packages:
- name: lvms-operator
additionalImages:
- name: registry.example.com/app:1.0
```

Outputs under `--output-dir`:

- `imagesetconfig.yaml`
- `values-disconnected.yaml`
- `mirror-commands.sh`
- `CHECKLIST.md`
- cloned pattern repo (when source is a Git URL)

### Move content into the airgap

Copy `--output-dir` to the disconnected bastion, mirror images into the registry, and push the pattern Git history into your internal SCM.

### Prepare the pattern

```bash
cd ~/mcgodemo/multicloud-gitops
patternizer upgrade
```

`upgrade` refreshes `Makefile-common` and `pattern.sh` with airgap-aware targets (including `install-airgap`).

### Configure secrets and bootstrap

Copy the secrets template and add an `airgap:` section (same `path` / `value` style as Vault secrets; **not** loaded into Vault). Declare Git/registry CA paths, registry credentials (`dockerconfig` or username/password), `registry`, and `ocpVersion` (or explicit `catalogSources` / `discoverCatalogs`).

```bash
cp values-secret.yaml.template ~/values-secret-multicloud-gitops.yaml
# edit airgap: certificates, registries, registry, ocpVersion, …

patternizer airgap bootstrap /path/to/multicloud-gitops \
--output-dir ./airgap-bootstrap \
--discover-catalogs \
--secrets-file ~/values-secret-multicloud-gitops.yaml
```

Bootstrap ingests that file, optionally discovers CatalogSources, and updates `values-global.yaml` and variant values (`helmRepoUrl`, operator sources, and related disconnected fields).

Lower-level helpers remain available without a values-secret file: `airgap trust-ca` and `airgap repo-creds`.

### Install

```bash
git add . && git commit -m 'patternizer airgap bootstrap' && git push
./pattern.sh make install-airgap
```

`install-airgap` applies proxy / user-CA trust, runs `make install` in the background, waits for GitOps, then applies TLS trust and registry repo-creds so Argo CD can sync—avoiding the deadlock where install never finishes until post-trust is applied.

## Further reading

<!-- - [Disconnected Patterns UX Update](https://validatedpatterns.io/blog/2026-10-26-disconnected-updates/) -->
- [Disconnected installation guide](https://validatedpatterns.io/learn/disconnected-installation/)
- [Patternizer README](./README.md) — full CLI examples for `airgap init`, `trust-ca`, `repo-creds`, and bootstrap
225 changes: 223 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Patternizer

![Version: 2.3.1](https://img.shields.io/badge/Version-2.3.1-informational?style=flat-square)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's quite a leap in minor version

![Version: 2.13.1](https://img.shields.io/badge/Version-2.13.1-informational?style=flat-square)
[![Quay Repository](https://img.shields.io/badge/Quay.io-patternizer-blue?logo=quay)](https://quay.io/repository/validatedpatterns/patternizer)
[![CI Pipeline](https://github.com/validatedpatterns/patternizer/actions/workflows/build-push.yaml/badge.svg?branch=main)](https://github.com/validatedpatterns/patternizer/actions/workflows/build-push.yaml)

Expand All @@ -17,6 +17,7 @@
- [**Initialize with secrets support:**](#initialize-with-secrets-support)
- [**Upgrade an existing pattern repository:**](#upgrade-an-existing-pattern-repository)
- [**Shell alias (optional):**](#shell-alias-optional)
- [**Airgap / disconnected:**](./airgap.md)
- [Understanding Secrets Management](#understanding-secrets-management)
- [Generated Files](#generated-files)
- [AI Coding Skills](#ai-coding-skills)
Expand Down Expand Up @@ -120,7 +121,227 @@ pattern() {
}
```

Then run commands as `pattern init`, `pattern upgrade`, etc.
Then run commands as `pattern init`, `pattern upgrade`, `pattern airgap init`, etc.

#### **Airgap / disconnected init:**

For a workflow summary (init → mirror → bootstrap → `install-airgap`), see [AIRGAP.md](./AIRGAP.md).

Generate an oc-mirror v2 `imagesetconfig.yaml` plus disconnected install helpers from a local absolute path or a Git URL.

Path-based Helm charts referenced by pattern applications (`path: charts/...`)
are scanned for container images (via `helm template` and values scrape); those
images are emitted under `additionalImages` only (the charts are not added to
`helm.local`). Remote OCI charts (`chart:` / `chartVersion:`) are resolved and
scanned as well. Use `--extra-config` for extra operators, images, and charts
not declared in values:

```yaml
# ~/extra-images.yaml
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.22
packages:
- name: lvms-operator
additionalImages:
- name: registry.example.com/app:1.0
helm:
local:
- name: my-chart
path: /abs/path/to/chart
```

```bash
# Absolute path to a local pattern checkout
podman run --pull=newer -v "$PWD:$PWD:z" -v "$HOME:$HOME:z" -w "$PWD" quay.io/validatedpatterns/patternizer \
airgap init /path/to/multicloud-gitops \
--extra-config "$HOME/extra-images.yaml" \
--output-dir "$PWD/airgap-out"

# Include OpenShift platform channel and tag OLM catalogs for that version
podman run --pull=newer -v "$PWD:$PWD:z" -v "$HOME:$HOME:z" -w "$PWD" quay.io/validatedpatterns/patternizer \
airgap init /path/to/multicloud-gitops \
--ocp-version 4.22 \
--extra-config "$HOME/extra-images.yaml" \
--output-dir "$PWD/airgap-out"

# Or clone from Git into --output-dir (override with --clone-dir)
podman run --pull=newer -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer \
airgap init https://github.com/validatedpatterns/multicloud-gitops \
--git-ref main \
--download-oc-mirror \
--output-dir "$PWD/airgap-out"
```

`--registry` is optional (sets `helmRepoUrl` in `values-disconnected.yaml` and the
registry placeholder in `mirror-commands.sh`). `--ocp-version` is optional: when set
it adds `mirror.platform` with channel `stable-<version>` and tags pattern-discovered
OLM catalog indexes / CatalogSource names with that version (default catalog tag is
`4.22` when omitted).

Git clones land under `--output-dir/<repo-name>/`. Run `oc-mirror` yourself using
`mirror-commands.sh` (patternizer only generates the config and helpers).

Or from a pattern repository after `Makefile-common` includes the target:

```bash
./pattern.sh make airgap-init \
AIRGAP_EXTRA_OPTS="--extra-config $HOME/extra-images.yaml"
# Optional: AIRGAP_OCP_VERSION=4.22 AIRGAP_REGISTRY=mirror.example.com:8443
```

Outputs under `--output-dir`:

- `imagesetconfig.yaml`
- `values-disconnected.yaml`
- `mirror-commands.sh`
- `CHECKLIST.md` (pull secrets, CatalogSources, Git, Vault/ESO)
- cloned pattern repo (when source is a Git URL)

Parse oc-mirror logs for skipped `oci://` related images:

```bash
pattern airgap parse-mirror-log /path/to/oc-mirror.log
```

#### **Airgap trust CA (Argo CD / GitOps):**

Generate apply-ready artifacts so OpenShift GitOps trusts a private or self-signed
CA for HTTPS Git hosts (e.g. Gitea) or OCI registries (e.g. Quay mirror). Patternizer
only writes files; you apply them on a bastion with `oc` and your kubeconfig.

```bash
# Gitea (or any Git host) CA
podman run --pull=newer -v "$PWD:$PWD:z" -v /home/fedora/gitea_container_certs:/certs:z \
-w "$PWD" quay.io/validatedpatterns/patternizer \
airgap trust-ca \
--ca /certs/ca.crt \
--host gitea-gitea.apps.airgap.rhuk.lab \
--namespace vp-gitops \
--output-dir "$PWD/airgap-trust"

# Mirror registry CA (hostname only; no port)
patternizer airgap trust-ca \
--ca /etc/pki/ca-trust/source/anchors/quay-rootCA.pem \
--host mirror.airgap.rhuk.lab \
--output-dir ./airgap-trust
```

`--ca` may be a PEM file or a directory of `.crt`/`.pem` files. `--host` is
repeatable (or comma-separated); URLs and `:port` suffixes are normalized to
hostname keys for `argocd-tls-certs-cm`.

Outputs under `--output-dir`:

- `argocd-tls-certs-patch.yaml`
- `trusted-ca-bundle-append.pem`
- `apply-trust-ca.sh` (run on the bastion)
- `README.md`

```bash
# On the bastion (cluster reachable via ~/.kube/config or KUBECONFIG):
./airgap-trust/apply-trust-ca.sh
```

#### **Airgap registry repo-creds (Argo CD auth):**

After TLS trust is in place, Argo CD still needs credentials to pull OCI charts from a
private mirror (otherwise sync fails with `401 unauthorized`). Generate a
`repo-creds` Secret from a docker config **or** username/password — credentials are
never hardcoded in patternizer:

```bash
# From ~/.docker/config.json (or podman containers auth.json)
patternizer airgap repo-creds \
--docker-config ~/.docker/config.json \
--url mirror.airgap.rhuk.lab:8443 \
--namespace vp-gitops \
--output-dir ./airgap-repo-creds

# Or explicit credentials (prefer --password-file)
patternizer airgap repo-creds \
--url mirror.example.com:8443 \
--username init \
--password-file /path/to/registry.password \
--output-dir ./airgap-repo-creds
```

`--url` keeps the port (e.g. `:8443`) for Argo CD. With multiple `auths` in the docker
config, `--url` selects which registry entry to use.

Outputs under `--output-dir`:

- `argocd-repo-creds-secret.yaml` (mode `0600` — **do not commit**)
- `apply-repo-creds.sh`
- `README.md`

```bash
./airgap-repo-creds/apply-repo-creds.sh
```

#### **Airgap bootstrap (recommended one-shot):**

Configure hostnames, CA files, and registry credentials in the pattern’s
`values-secret.yaml` / `~/values-secret-<pattern>.yaml` under a top-level `airgap:`
section (same `path` / `value` field style as Vault secrets; **not** loaded into Vault).

Then install with the airgap-aware target (leaves `make install` unchanged for connected clusters):

```bash
# Edit airgap: in ~/values-secret-multicloud-gitops.yaml (see values-secret.yaml.template)
./pattern.sh make install-airgap
```

That runs:

1. `airgap-trust-pre` — Proxy CA / `user-ca-bundle`
2. **`make install` in the background** (log: `airgap-bootstrap/install.log`)
3. `airgap-wait-gitops` — waits for `vp-gitops` while install is still running
4. `airgap-trust-post` — repo-creds + TLS (unblocks Argo CD / install)
5. Waits for the background `make install` to finish

This avoids the deadlock where install never completes until post trust is applied.
Default wait is 20 minutes (`AIRGAP_WAIT_SECONDS=1200`):

```bash
./pattern.sh make install-airgap AIRGAP_WAIT_SECONDS=1800
```

Stop a running session with **Ctrl-C**, or from another shell: `./pattern.sh make airgap-abort`.

Declare CatalogSources in `~/values-secret-<pattern>.yaml` under `airgap:`:

```yaml
airgap:
registry: mirror.airgap.rhuk.lab:8443
ocpVersion: "4.22" # derives cs-*-operator-index-v4-22
# Or:
# catalogSources:
# redhat: cs-redhat-operator-index-v4-22
# community: cs-community-operator-index-v4-22
# Or: discoverCatalogs: true # uses oc get catalogsource
```

Manual generate:

```bash
patternizer airgap bootstrap /home/fedora/multicloud-gitops \
--output-dir ./airgap-bootstrap
# or: --discover-catalogs # requires oc/kubeconfig
```

Proxy backup is written to `./airgap-bootstrap/backup/proxy-cluster.yaml`. Restore with:

```bash
./pattern.sh make airgap-restore-proxy
```

Overrides: `AIRGAP_BOOTSTRAP_DIR`, `AIRGAP_SECRETS_FILE`, `AIRGAP_PATTERNIZER_BIN`,
`AIRGAP_PATTERNIZER_IMAGE`, `AIRGAP_WAIT_SECONDS`.

Lower-level commands `airgap trust-ca` and `airgap repo-creds` remain available
for one-off use without a values-secret file.

See [airgap.md](./airgap.md) for a workflow summary, and the [disconnected installation guide](https://validatedpatterns.io/learn/disconnected-installation/).

What upgrade does:

Expand Down
Loading
Loading