Patternizer

Patternizer is a command-line tool that bootstraps a Git repository containing Helm charts into a ready-to-use Validated Pattern. It automatically generates the necessary scaffolding, configuration files, and utility scripts, so you can get your pattern up and running in minutes.

Note: This tool was developed with assistance from Cursor, an AI-powered code editor.

• Patternizer
  • Features
  • Quick Start
  • Example Workflow
  • Usage Details
    • Container Usage (Recommended)
      • Initialize without secrets:
      • Initialize with secrets support:
      • Upgrade an existing pattern repository:
    • Understanding Secrets Management
    • Generated Files
  • Development & Contributing
    • Prerequisites
    • Local Development Workflow
    • Common Makefile Targets
    • Testing Strategy
    • Architecture
    • CI/CD Pipeline
    • How to Contribute

Features

• 🚀 CLI-first design with intuitive commands and help system
• 📦 Container-native for consistent execution across all environments
• 🔍 Auto-discovery of Helm charts and Git repository metadata
• 🔐 Optional secrets integration with Vault and External Secrets
• 🏗️ Makefile-driven utility scripts for easy pattern management
• ♻️ Upgrade command to refresh existing pattern repositories to the latest common structure

Quick Start

This guide assumes you have a Git repository containing one or more Helm charts.

Prerequisites:

• Podman or Docker
• A Git repository you want to convert into a pattern

Navigate to your repository's root directory and run the initialization command:

# In the root of your pattern-repo
podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer init

This single command will generate all the necessary files to turn your repository into a Validated Pattern.

Example Workflow

1. Clone or create your pattern repository:

   git clone https://github.com/your-org/your-pattern.git
   cd your-pattern
   git checkout -b initialize-pattern

2. Initialize the pattern using Patternizer:

   podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer init

3. Review, commit, and push the generated files:

   git status
   git add .
   git commit -m 'initialize pattern using patternizer'
   git push -u origin initialize-pattern

4. Install the pattern:

   ./pattern.sh make install

Usage Details

Container Usage (Recommended)

Using the prebuilt container is the easiest way to run Patternizer, as it requires no local installation. The -v "$PWD:$PWD:z" -w "$PWD" flag mounts your current directory into the container's /repo workspace.

Initialize without secrets:

podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer init

Initialize with secrets support:

podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer init --with-secrets

Upgrade an existing pattern repository:

Use this to migrate or refresh an existing pattern repo to the latest common structure and scripts.

# Refresh common assets, keep your Makefile unless it lacks the include
podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer upgrade

# Replace your Makefile with the default from Patternizer
podman run -v "$PWD:$PWD:z" -w "$PWD" quay.io/validatedpatterns/patternizer upgrade --replace-makefile

What upgrade does:

• Removes the common/ directory if it exists
• Removes ./pattern.sh if it exists (symlink or file)
• Copies resources/Makefile-common and resources/pattern.sh into the repo root
• Makefile handling:
  • If --replace-makefile is set: copies the default Makefile into the repo root (overwriting any existing one)
  • If not set:
    • If no Makefile exists: copies the default Makefile
    • If a Makefile exists and already contains include Makefile-common anywhere: leaves it unchanged
    • Otherwise: prepends include Makefile-common to the first line so your existing targets are preserved

Understanding Secrets Management

You can start simple and add secrets management later.

• By default, patternizer init disables secret loading.
• To add secrets scaffolding, run patternizer init --with-secrets at any time. This will update your configuration to enable secrets.
• Important: This action is not easily reversible. We recommend committing your work to Git before adding secrets support.

For more details on how secrets work in the framework, see the Secrets Management Documentation.

Generated Files

Running patternizer init creates the following:

• values-global.yaml: Global pattern configuration.
• values-<cluster_group>.yaml: Cluster group-specific values.
• pattern.sh: A utility script for common pattern operations (install, upgrade, etc.).
• Makefile: A simple Makefile that includes Makefile-common.
• Makefile-common: The core Makefile with all pattern-related targets.

Using the --with-secrets flag additionally creates:

• values-secret.yaml.template: A template for defining your secrets.
• It also updates values-global.yaml to set global.secretLoader.disabled: false and adds Vault and External Secrets Operator to the cluster group values.

Development & Contributing

This section is for developers who want to contribute to the Patternizer project itself.

Prerequisites

• Go (see go.mod for version)
• Podman or Docker
• Git
• Make

Local Development Workflow

# 1. Clone the repository
git clone https://github.com/dminnear-rh/patternizer.git
cd patternizer

# 2. Set up the development environment (installs tools)
make dev-setup

# 3. Make your changes...

# 4. Run the full CI suite locally before committing
make ci

Common Makefile Targets

The Makefile is the single source of truth for all development and CI tasks.

• make help: Show all available targets.
• make check: Quick feedback loop (format, vet, build, unit tests).
• make build: Build the patternizer binary.
• make test: Run all tests (unit and integration).
• make test-unit: Run unit tests only.
• make test-integration: Run integration tests only.
• make lint: Run all code quality checks.
• make amd64: Build the amd64 container image locally.
• make arm64: Build the arm64 container image locally.

Testing Strategy

Patternizer has a comprehensive test suite to ensure stability and correctness.

• Unit Tests: Located alongside the code they test (e.g., src/internal/helm/helm_test.go), these tests cover individual functions and packages in isolation. They validate Helm chart detection, Git URL parsing, and YAML processing logic.
• Integration Tests: The integration test suite (test/integration_test.sh) validates the end-to-end CLI workflow against a real Git repository. Key scenarios include:
  1. Basic Init: Validates default file generation without secrets.
  2. Init with Secrets: Ensures secrets-related applications and files are correctly added.
  3. Configuration Preservation: Verifies that existing custom values are preserved when the tool is re-run.
  4. Sequential Execution: Tests running init and then init --with-secrets to ensure a clean upgrade.
  5. Selective File Overwriting: Confirms that running init on a repository with pre-existing custom files correctly merges YAML configurations, preserves user-modified files (like Makefile and values-secret.yaml.template), and only overwrites essential, generated scripts (pattern.sh, Makefile-common).
  6. Mixed State Handling: Validates that the tool correctly initializes a partially-configured repository, creating files that are missing while leaving existing ones untouched.
  7. Upgrade (no replace): Removes legacy common/ and pattern.sh symlink, copies Makefile-common/pattern.sh, and injects include Makefile-common at the top of Makefile when missing.
  8. Upgrade (include present): Leaves the existing Makefile unchanged when it already contains include Makefile-common anywhere.
  9. Upgrade with --replace-makefile: Replaces Makefile with the default and refreshes common assets.
  10. Upgrade (no Makefile present): Creates the default Makefile and refreshes common assets when a Makefile does not exist.

Architecture

The CLI is organized into focused packages following Go best practices, with a clean separation of concerns between command-line logic (cmd), core business logic (internal), and file operations (fileutils). This modular design makes the codebase maintainable, testable, and extensible.

CI/CD Pipeline

The GitHub Actions pipeline (.github/workflows/ci.yaml) runs on every push and pull request. It uses the same Makefile targets that developers use locally, ensuring perfect consistency between local and CI environments.

How to Contribute

1. Fork the repository.
2. Create a feature branch for your changes.
3. Make your changes and ensure they pass the local CI check (make ci).
4. Submit a pull request.