### Install pre-commit tool

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Install the pre-commit package using pip and verify the installation. This is the first step before setting up hooks in a repository.

```bash
# Install pre-commit (if not already installed)
pip install pre-commit

# Verify installation
pre-commit --version
```

--------------------------------

### Install Prerequisites for macOS

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Installs Podman Desktop and ansible-navigator for macOS users.

```bash
# Install Podman Desktop
# Download from: https://podman-desktop.io/

# Install ansible-navigator
pip3 install ansible-navigator
```

--------------------------------

### Install Prerequisites for Ubuntu/Debian

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Installs Podman and ansible-navigator using apt-get and pip for Ubuntu and Debian systems.

```bash
# Install Podman
sudo apt-get update
sudo apt-get install podman

# Install ansible-navigator
pip install ansible-navigator
```

--------------------------------

### Import Common Git Subtree - Script Method

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Imports the common git subtree using a provided script. This is the recommended method for the first-time setup of the common subtree, which contains essential pattern installation Helm charts, ArgoCD configuration, and secrets management.

```bash
./common/scripts/make_common_subtree.sh
```

--------------------------------

### Install Prerequisites for Fedora/RHEL/CentOS

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Installs Podman, ansible-navigator, and the OpenShift CLI using DNF package manager and pip for Fedora, RHEL, and CentOS systems.

```bash
# Install Podman
sudo dnf install podman

# Install ansible-navigator
pip install ansible-navigator

# Install OpenShift CLI
# Download from: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/
```

--------------------------------

### GitOps Deployment with ArgoCD

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/QUICK-START.md

Commands for deploying an application using ArgoCD and monitoring its synchronization status within OpenShift. Assumes ArgoCD is installed and configured.

```bash
# Deploy using ArgoCD
oc apply -f gitops/application.yaml

# Monitor sync
oc get application reference-app -n openshift-gitops -w

# Check ArgoCD status
oc describe application reference-app -n openshift-gitops
```

--------------------------------

### Verify Required Tools Installation

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/tests/week10/QUICKSTART.md

Checks that all necessary command-line tools are installed and accessible. Validates versions of oc, ansible-playbook, kubectl, curl, and jq for cluster management and testing operations.

```bash
# Verify tools are installed
oc version
ansible-playbook --version
kubectl version --client
curl --version
jq --version
```

--------------------------------

### Setup Gitea for Local Development

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Deploys Gitea using a Makefile target for local development and retrieves Gitea credentials.

```bash
# Deploy Gitea for local development
make setup-gitea

# Get Gitea credentials
./gitea/scripts/get-credentials.sh
```

--------------------------------

### Build Application and Container Image

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/QUICK-START.md

Commands to build the Quarkus reference application and its container image. Assumes you are in the project root directory.

```bash
cd quarkus-reference-app
./mvnw clean package
```

```bash
podman build -f src/main/docker/Dockerfile.jvm -t reference-app:latest .
```

--------------------------------

### Navigate to Week 10 Test Directory

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/tests/week10/QUICKSTART.md

Changes to the test directory and verifies the directory structure is properly set up for running Week 10 tests.

```bash
# Navigate to test directory
cd tests/week10

# Verify directory structure
ls -la
```

--------------------------------

### Run Deployment with Ansible Navigator (Bash)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/END-USER-GUIDE.md

Demonstrates how to use `ansible-navigator` to run the deployment playbook, including an example with a specified execution environment.

```bash
# Deploy with ansible-navigator
ansible-navigator run deploy.yml

# With execution environment
ansible-navigator run deploy.yml \
  --execution-environment-image quay.io/ansible/creator-ee:latest
```

--------------------------------

### Install and Configure Pre-commit Hooks - Bash

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/MIGRATION-GUIDE.md

Installs pre-commit framework and activates security and quality hooks for the new repository. Includes commands to install pre-commit, initialize hooks for the repository, and test all hooks against the codebase.

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Test hooks
pre-commit run --all-files
```

--------------------------------

### Deploy Pattern (Bash)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/adr/ADR-007-ansible-navigator-deployment.md

This example shows the steps for a first-time user to install prerequisites, clone the repository, log in to an OpenShift cluster, and deploy a pattern. It requires Podman and ansible-navigator to be installed.

```bash
# Install prerequisites
sudo dnf install podman
pip install ansible-navigator

# Clone and deploy
git clone https://github.com/your-org/validated-patterns-ansible-toolkit.git
cd validated-patterns-ansible-toolkit
oc login
make deploy-pattern PATTERN_NAME=multicloud-gitops
```

--------------------------------

### Troubleshoot Performance Issues

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/tests/week10/QUICKSTART.md

Analyzes application performance by checking logs, monitoring resource usage, and scaling deployments. Provides commands to adjust resource limits and replicas.

```bash
# Check application logs
oc logs -f deployment/reference-app -n reference-app

# Check resource usage
oc adm top pods -n reference-app

# Scale up if needed
oc scale deployment reference-app --replicas=5 -n reference-app
```

```bash
# Check resource limits
oc describe deployment reference-app -n reference-app

# Adjust resource limits if needed
oc set resources deployment reference-app \
  --limits=cpu=1000m,memory=512Mi \
  --requests=cpu=200m,memory=256Mi \
  -n reference-app
```

--------------------------------

### Deploy to OpenShift (Development)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/QUICK-START.md

Steps to deploy the application to an OpenShift development environment using Kustomize. This includes creating a namespace and applying the Kustomize configuration.

```bash
# Create namespace
oc new-project reference-app-dev

# Deploy using Kustomize
oc apply -k k8s/overlays/dev

# Wait for deployment
oc rollout status deployment/dev-reference-app -n reference-app-dev
```

--------------------------------

### Install with Global and Development Values

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/VALUES-README.md

Illustrates the Helm installation process for the Quarkus reference application, combining global and development environment values. This is used to set up the application for a development environment with specific overrides.

```bash
helm install quarkus-reference-app ./charts/all/quarkus-reference-app \
  -f values-global.yaml \
  -f values-dev.yaml
```

--------------------------------

### Install GitOps with Ansible Navigator (Bash)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/GUIDES-INDEX.md

Shows the command to install OpenShift GitOps using `ansible-navigator`. This command executes the `install_gitops.yml` playbook, which is part of the common infrastructure setup for pattern development.

```bash
# 4. Deploy common infrastructure
ansible-navigator run ansible/playbooks/install_gitops.yml
```

--------------------------------

### Test all pre-commit hooks

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Run pre-commit hooks on all repository files to verify configuration and identify issues. First run may take several minutes to set up environments.

```bash
# Run hooks on all files (optional, but recommended)
pre-commit run --all-files

# This will check all files in the repository
# First run may take a few minutes to set up environments
```

--------------------------------

### Clone Repository and Deploy

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/RELEASE-QUICK-REFERENCE.md

Clone the repository, configure values files, and deploy the complete pattern using Ansible. This is the primary method for users to get started.

```bash
git clone https://github.com/tosin2013/validated-patterns-ansible-toolkit.git
cd validated-patterns-ansible-toolkit
vi values-global.yaml
vi values-hub.yaml
ansible-playbook ansible/playbooks/deploy_complete_pattern.yml
```

--------------------------------

### Install with Global and Production Values

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/VALUES-README.md

Provides the Helm command to install the Quarkus reference application using global and production environment values. This configures the application for a production environment with high availability and performance settings.

```bash
helm install quarkus-reference-app ./charts/all/quarkus-reference-app \
  -f values-global.yaml \
  -f values-prod.yaml
```

--------------------------------

### API Examples (RESTful)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/QUICK-START.md

Example `curl` commands for interacting with the application's RESTful API, covering GET (all, by ID), POST, PUT, and DELETE operations.

```bash
# Get All Examples
curl https://$ROUTE/api/example

# Create Example
curl -X POST https://$ROUTE/api/example \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Example",
    "description": "This is an example"
  }'

# Get Example by ID
curl https://$ROUTE/api/example/1

# Update Example
curl -X PUT https://$ROUTE/api/example/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Example",
    "description": "Updated description"
  }'

# Delete Example
curl -X DELETE https://$ROUTE/api/example/1
```

--------------------------------

### Gitea Development Setup and Repository Management

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

This section details commands for setting up and interacting with a Gitea instance for development. It includes deploying Gitea, creating and pushing repositories, and managing branches for feature development. These commands leverage `make` for streamlined operations.

```bash
# Deploy Gitea
make setup-gitea

# Access Gitea
# URL: https://gitea-gitea.apps.<cluster-domain>
# Default credentials: gitea / gitea
```

```bash
# Create development repository
make gitea-create-repo REPO_NAME=my-pattern

# Push project to Gitea
make gitea-push-project PROJECT_PATH=./my-pattern REPO_NAME=my-pattern

# View Gitea repositories
make gitea-list-repos
```

--------------------------------

### Install pre-commit hooks in repository

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Navigate to the repository root and install pre-commit hooks. This sets up the git hook that runs checks before each commit.

```bash
# Navigate to repository root
cd /path/to/validated-patterns-ansible-toolkit

# Install pre-commit hooks
pre-commit install

# You should see:
# pre-commit installed at .git/hooks/pre-commit
```

--------------------------------

### View Ansible Toolkit Documentation and Help

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Displays help information for the deployment workflow, onboarding options, and the main onboarding guide. Useful for understanding available commands and documentation.

```bash
make end2end-help
make onboard-help
cat ONBOARDING.md
```

--------------------------------

### Pre-commit Installation and Usage (Bash)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/adr/ADR-014-pre-commit-hooks-gitleaks.md

Provides the necessary bash commands to install the pre-commit framework, install the git hooks defined in the configuration, and run the checks manually. This section guides developers through the initial setup and daily usage of pre-commit for maintaining code quality and security.

```bash
# Install pre-commit (one-time)
pip install pre-commit

# Install git hooks (one-time per clone)
pre-commit install

# Test configuration
pre-commit run --all-files
```

--------------------------------

### Setup Development Environment with Ansible Toolkit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Sets up the development environment by checking prerequisites, deploying Gitea for local development, and performing a complete end-to-end deployment of the pattern. These commands are essential for local development and testing.

```bash
make check-prerequisites
make setup-gitea
make end2end-deployment
```

--------------------------------

### Troubleshoot Deployment Failures

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/tests/week10/QUICKSTART.md

Investigates deployment issues by checking pod status, viewing logs, and examining cluster events. Helps identify application startup problems and configuration errors.

```bash
# Check pod status
oc get pods -n quarkus-dev
oc get pods -n reference-app

# Check pod logs
oc logs -f deployment/dev-reference-app -n quarkus-dev
oc logs -f deployment/reference-app -n reference-app

# Check events
oc get events -n quarkus-dev --sort-by='.lastTimestamp'
```

--------------------------------

### Example Integration Test with Quarkus

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/docs/DEVELOPMENT.md

An example integration test for 'ExampleResource' using `@QuarkusTest`. It uses RestAssured (implicitly via `given()`) to send a GET request to '/api/example' and asserts that the HTTP status code is 200.

```java
@QuarkusTest
public class ExampleResourceTest {
    @Test
    public void testGetAll() {
        given()
            .when().get("/api/example")
            .then()
            .statusCode(200);
    }
}
```

--------------------------------

### Best Practice: Use Make Targets vs. Direct Commands

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Illustrates the recommended approach of using 'make' targets for deploying patterns, contrasting it with complex direct 'ansible-navigator' commands for better readability and maintainability.

```bash
# ✅ Good: Use Make targets
make deploy-pattern PATTERN_NAME=multicloud-gitops
```

```bash
# ❌ Avoid: Complex ansible-navigator commands
ansible-navigator run ansible/playbooks/deploy_pattern.yml \
  --eei localhost/ansible-ee-minimal:v5 \
  --ce podman \
  -m stdout \
  -e pattern_name=multicloud-gitops
```

--------------------------------

### Fix auto-fixable pre-commit issues

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Example showing how to handle hooks that automatically fix issues like trailing whitespace. Demonstrates restaging the modified files and retrying the commit.

```bash
$ git commit -m "docs: update README"

Trim trailing whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook

Fixing README.md

# The hook fixed the file automatically
# Just stage the changes and commit again
$ git add README.md
$ git commit -m "docs: update README"
```

--------------------------------

### New Project Onboarding Workflow - Bash

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Complete workflow for initializing a new project from scratch. Creates directory structure, Helm charts, application files, initializes git repository, deploys Gitea, and creates development memory documentation.

```bash
# 1. Detect cluster requirements
make cluster-info

# 2. Validate cluster prerequisites
make check-prerequisites

# 3. Setup development environment (Gitea + pattern)
make onboard-new-project PROJECT_NAME=my-project

# 4. View onboarding status
make onboard-status PROJECT_NAME=my-project
```

--------------------------------

### Handle pre-commit hook failure - secret detection

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Example demonstrating a failed gitleaks hook that detected a secret in a file. Shows the error message, secret details, and guidance for resolving the issue.

```bash
$ git commit -m "feat: add configuration"

Detect secrets with gitleaks.............................................Failed
- hook id: gitleaks
- exit code: 1

Finding:     token: j0sBFggYvrMlHdp0LTtn1VD0so6OlsZI
Secret:      j0sBFggYvrMlHdp0LTtn1VD0so6OlsZI
RuleID:      validated-patterns-token
File:        values-global.yaml
Line:        19

❌ Secret detected! Please remove the secret and try again.
```

--------------------------------

### Onboard New Quarkus Application with Toolkit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Guides through creating a new Quarkus project using the toolkit's 'onboard-new-project' make target, inspecting the created files, updating development memory, and deploying the pattern. It also covers making local changes, committing, pushing, and releasing the project.

```bash
# Create new pattern with Quarkus
make onboard-new-project PROJECT_NAME=my-quarkus-app

# View what was created
cd my-quarkus-app
ls -la

# Edit development memory
vim DEVELOPMENT-MEMORY.md

# Access Gitea and view repository
make gitea-list-repos

# Deploy pattern
make end2end-deployment

# Make changes
vim src/main/java/MyService.java
git add .
git commit -m "feat: add business logic"
git push origin main

# Release to GitHub
make release VERSION=v1.0.0
```

--------------------------------

### Successful pre-commit hook execution

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Example output showing all pre-commit hooks passing successfully during a git commit operation, including standard checks, security validation, and code quality linting.

```bash
$ git commit -m "feat: add new feature"

Trim trailing whitespace.................................................Passed
Fix end of files.........................................................Passed
Check YAML syntax........................................................Passed
Check for large files....................................................Passed
Check for merge conflicts................................................Passed
Check for case conflicts.................................................Passed
Check for mixed line endings.............................................Passed
Detect secrets with gitleaks.............................................Passed
Lint YAML files..........................................................Passed

[main abc1234] feat: add new feature
 1 file changed, 10 insertions(+)
```

--------------------------------

### Allowlist Configuration for Gitleaks

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Defines file patterns to be excluded from Gitleaks scanning. This TOML configuration specifies paths that may contain example secrets or are intended for testing, preventing false positives during secret detection.

```toml
[allowlist]
paths = [
  '''values-secrets\.yaml\.template''',
  '''tests/.*\.example''',
  '''your-new-pattern-here''',
]
```

--------------------------------

### Onboard Existing Python Flask Project with Toolkit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Demonstrates onboarding an existing Python Flask project. It covers viewing the integration guide, choosing integration options (Helm, Ansible, or isolation), deploying using the toolkit, making local changes, and managing releases with versioning and push to GitHub.

```bash
# Onboard existing Flask project
make onboard-existing-project PROJECT_NAME=my-flask-app

# View integration guide
cat my-flask-app/.validated-patterns/INTEGRATION-GUIDE.md

# Decide what to copy (gradual integration)
# Option A: Copy Helm chart for GitOps deployment
cp -r my-flask-app/.validated-patterns/helm/my-flask-app ./my-flask-app/helm/

# Option B: Copy Ansible playbooks for automation
cp -r my-flask-app/.validated-patterns/ansible ./my-flask-app/

# Option C: Keep toolkit isolated (recommended for existing projects)
# Just use .validated-patterns/values-*.yaml and keep everything else separate

# Deploy to cluster using toolkit
cd my-flask-app/.validated-patterns
make end2end-deployment

# Develop locally in your main project
cd /path/to/my-flask-app
git pull  # Get latest from Gitea

# Make changes, test locally
python -m pytest tests/

# Push development
git add .
git commit -m "test: add unit tests"
git push origin develop

# Prepare release
git checkout -b release/v2.0.0
# Update version files (Flask app)
vim setup.py  # Update version
git add .
git commit -m "chore: release v2.0.0"
git push origin release/v2.0.0

# Create pull request and merge
# Then push to GitHub
git push github release/v2.0.0

# Toolkit files stay isolated in .validated-patterns/
# Your project remains clean and independent
```

--------------------------------

### Handle YAML syntax errors in pre-commit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Example showing a failed YAML syntax check with error details including file location and line numbers. Demonstrates the need to fix YAML formatting before committing.

```bash
$ git commit -m "feat: add playbook"

Check YAML syntax........................................................Failed
- hook id: check-yaml
- exit code: 1

while parsing a block mapping
  in "ansible/playbooks/deploy.yml", line 10, column 3
did not find expected key
  in "ansible/playbooks/deploy.yml", line 15, column 5

# Fix the YAML syntax error in the file
# Then stage and commit again
```

--------------------------------

### Serve MkDocs Site Locally

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/how-to/build-docs-locally.md

This command serves the MkDocs generated documentation site locally on a specified address and port. It requires the documentation to be built first. The command will start a local development server, allowing you to preview the site at the provided URL. Ensure the virtual environment is active.

```bash
mkdocs serve -f mkdocs.yml/mkdocs.yml -a 127.0.0.1:8000
```

--------------------------------

### Allowing Specific Lines in Gitleaks Scans

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/CONTRIBUTING-PRE-COMMIT.md

Shows how to use an inline comment to instruct Gitleaks to ignore specific lines within a file. This is useful for intentionally including example secrets or sensitive-looking data that is not a real vulnerability.

```yaml
# gitleaks:allow
example_token: "this-is-just-an-example-not-real"
```

--------------------------------

### Verify Helm Installation

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/DEVELOPER-GUIDE.md

Checks the installed version of Helm to confirm a successful installation or to verify the version after manual installation or upgrade.

```bash
# Verify installation
helm version
```

--------------------------------

### GET /api/example/{id}

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/docs/ARCHITECTURE.md

Retrieves a specific example by its unique identifier. Returns the details of a single example object if found.

```APIDOC
## GET /api/example/{id}

### Description
Retrieve a specific example by its unique identifier. Returns a single example object with all its details.

### Method
GET

### Endpoint
/api/example/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - UUID of the example to retrieve

### Request Example
No request body required

### Response
#### Success Response (200)
- **id** (string) - Unique identifier (UUID) for the example
- **name** (string) - Name of the example
- **description** (string) - Description of the example
- **status** (string) - Status of the example

#### Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example 1",
  "description": "First example item",
  "status": "active"
}
```

--------------------------------

### GET /api/example

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/docs/ARCHITECTURE.md

Retrieves all examples from the in-memory data store. This endpoint returns a list of all available example objects with their complete details.

```APIDOC
## GET /api/example

### Description
Retrieve all examples from the in-memory data store. Returns a JSON array of all example objects.

### Method
GET

### Endpoint
/api/example

### Parameters
None

### Request Example
No request body required

### Response
#### Success Response (200)
- **id** (string) - Unique identifier (UUID) for the example
- **name** (string) - Name of the example
- **description** (string) - Description of the example
- **status** (string) - Status of the example

#### Response Example
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example 1",
    "description": "First example item",
    "status": "active"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Example 2",
    "description": "Second example item",
    "status": "inactive"
  }
]
```

--------------------------------

### Onboard New or Existing Project with Ansible Toolkit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Onboards a new or existing project using the provided make commands. This sets up the project structure and configurations based on the chosen path. Requires a PROJECT_NAME argument.

```bash
make onboard-new-project PROJECT_NAME=my-pattern
```

```bash
make onboard-existing-project PROJECT_NAME=my-project
```

--------------------------------

### Example Workflow: Build, Deploy, and Test Pattern

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/AGENTS.md

This snippet illustrates a typical workflow involving building, deploying, and testing a pattern using both the root `Makefile` and the `common/Makefile`. It shows how to build the EE, deploy the operator, validate prerequisites, and finally run end-to-end tests.

```bash
# Build EE (root Makefile)
make build test

# Deploy pattern (common Makefile)
make -f common/Makefile operator-deploy

# Validate deployment (common Makefile)
make -f common/Makefile validate-prereq argo-healthcheck

# Run e2e tests (root Makefile + ansible-navigator)
ansible-navigator run tests/integration/playbooks/test_end_to_end.yml

```

--------------------------------

### Install Required Ansible Collections

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/DEVELOPER-GUIDE.md

Installs the necessary Ansible collections for the validated patterns toolkit using the `requirements.yml` file. It then verifies the installation by listing installed collections, filtering for Kubernetes and community-related ones.

```bash
# Install required Ansible collections
ansible-galaxy collection install -r files/requirements.yml

# Verify installation
ansible-galaxy collection list | grep -E "kubernetes|community"
```

--------------------------------

### Ansible Collection Installation Example

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/GITHUB-ACTIONS-COLLECTION.md

This command shows how to install a specific version of an Ansible collection from Galaxy. It's used for testing after a release and requires Ansible to be installed on the target system. Replace 'X.Y.Z' with the version you wish to install.

```bash
ansible-galaxy collection install tosin2013.validated_patterns_toolkit:X.Y.Z
```

--------------------------------

### Start Deploying a Pattern

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

The primary command to initiate the deployment of a pattern using the Ansible Toolkit, specifying the desired pattern name.

```bash
make deploy-pattern PATTERN_NAME=multicloud-gitops
```

--------------------------------

### Clone Ansible Toolkit Repository

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Clones the Validated Patterns Ansible Toolkit repository to create a new project foundation. This is the first step in using the toolkit.

```bash
git clone https://github.com/tosin2013/validated-patterns-ansible-toolkit.git my-pattern
cd my-pattern
```

--------------------------------

### Check Operator Subscription and Installation Plan

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/TROUBLESHOOTING-COMPREHENSIVE.md

Verify operator subscription status and manage installation plan approval in OpenShift. Automatically approves pending install plans if manual approval is required.

```bash
# Check subscription
oc get subscription patterns-operator -n openshift-operators

# Check install plan
oc get installplan -n openshift-operators

# Manual approval if needed
INSTALL_PLAN=$(oc get installplan -n openshift-operators \
  -o jsonpath='{.items[0].metadata.name}')
oc patch installplan $INSTALL_PLAN -n openshift-operators \
  --type merge -p '{"spec":{"approved":true}}'
```

--------------------------------

### Install Ansible Collection

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/TROUBLESHOOTING-COMPREHENSIVE.md

Installs the specified Ansible collection, typically rhvp.cluster_utils. This ensures that necessary modules and roles are available for Ansible playbooks. It can be installed from a requirements file or directly by name and version.

```bash
# Install from requirements file
ansible-galaxy collection install -r files/requirements.yml

# Or install directly
ansible-galaxy collection install rhvp.cluster_utils:1.0.0

# Verify installation
ansible-galaxy collection list | grep rhvp
```

--------------------------------

### Build or Pull Execution Environment

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/tutorials/quick-start-ansible-navigator.md

Provides options to build the Ansible execution environment locally using 'make build' or pull a pre-built image using 'make pull-ee' or directly with Podman.

```bash
# Set your Ansible Hub token
export ANSIBLE_HUB_TOKEN=your_token_here

# Build the execution environment
make build

# This creates: localhost/ansible-ee-minimal:v5
```

```bash
# Pull the published image
make pull-ee

# Or manually:
podman pull quay.io/validated-patterns/ansible-ee:latest
```

--------------------------------

### Troubleshoot Operator Installation Failure (OpenShift CLI)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/END-USER-GUIDE.md

Provides commands to diagnose and resolve operator installation failures on OpenShift. It checks the subscription status, install plan, operator logs, and includes steps for manual approval of the install plan if necessary. Requires `oc` CLI access.

```bash
# Check operator subscription
oc get subscription patterns-operator -n openshift-operators

# Check install plan
oc get installplan -n openshift-operators

# Check operator logs
oc logs -n openshift-operators -l name=patterns-operator

# Manual approval if needed
INSTALL_PLAN=$(oc get installplan -n openshift-operators -o jsonpath='{.items[0].metadata.name}')
oc patch installplan $INSTALL_PLAN -n openshift-operators \
  --type merge -p '{"spec":{"approved":true}}'
```

--------------------------------

### First-time Setup for Common Subtree

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/AGENTS.md

This snippet shows the command to execute for the initial setup of the 'common/' git subtree. It's a one-time command used when the common directory does not yet exist in the repository.

```bash
./common/scripts/make_common_subtree.sh

```

--------------------------------

### Yamllint Configuration Example

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/adr/ADR-014-pre-commit-hooks-gitleaks.md

Configuration file for Yamllint, defining rules and preferences for linting YAML files. This setup includes a 120-character line length limit (as a warning), 2-space indentation, exclusions for Helm templates, and specific allowances for truthy values and document start markers. This allows for flexible yet consistent YAML formatting.

```yaml
# .yamllint
# Line length warning
line-length:
  max: 120
  level: warning

# Indentation
indentation: 2

# Allow Helm templates to be excluded
exclude: |
  (?x)
  ^quarkus-reference-app/charts/.*/templates/.*

# Allow truthy values like yes/no/on/off
truthy:
  - 'yes'
  - 'no'
  - 'on'
  - 'off'

# Document start is optional
document-start:
  require: false
```

--------------------------------

### Onboard OpenShift AI Project with Toolkit

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

This example details onboarding an OpenShift AI pattern. It includes checking for the RHOAI operator, updating development memory, deploying the pattern with AI components, accessing notebooks via Gitea, and pushing changes made in the OpenShift AI UI.

```bash
# Onboard OpenShift AI pattern
make onboard-existing-project PROJECT_NAME=ai-ml-patterns

# Check cluster for RHOAI operator
make cluster-info

# Update development memory with AI-specific info
vim DEVELOPMENT-MEMORY.md

# Deploy pattern with AI components
make end2end-deployment

# Access notebooks in Gitea
make gitea-list-repos

# Develop in OpenShift AI UI
# Push changes to Gitea
git add .
git commit -m "feat: train new model"
git push origin main

# Release trained model to GitHub
make release VERSION=v1.0.0
```

--------------------------------

### Manual Installation of OpenShift GitOps

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/openshift-gitops/README.md

Installs OpenShift GitOps operator, waits for it to be ready, applies RBAC permissions, and creates the ArgoCD instance manually using `oc` commands.

```bash
# Install operator
oc apply -f openshift-gitops/operator.yaml

# Wait for operator to be ready
oc wait --for=condition=Ready csv -l operators.coreos.com/openshift-gitops-operator.openshift-operators -n openshift-operators --timeout=300s

# Apply RBAC
oc apply -f openshift-gitops/rbac.yaml

# Create ArgoCD instance
oc apply -f openshift-gitops/argocd.yaml
```

--------------------------------

### Troubleshoot OpenShift Pod Not Starting

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/docs/DEPLOYMENT.md

Provides commands to diagnose issues with pods that are not starting in OpenShift. It involves checking pod descriptions and logs.

```bash
oc describe pod <pod-name> -n reference-app
oc logs <pod-name> -n reference-app
```

--------------------------------

### Debug Operator Installation Issues

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/TROUBLESHOOTING-COMPREHENSIVE.md

Comprehensive debugging commands for operator installation failures. Checks events, deployments, and service accounts related to patterns-operator.

```bash
# Check operator events
oc get events -n openshift-operators --sort-by='.lastTimestamp'

# Check operator deployment
oc get deployment -n openshift-operators | grep patterns

# Check operator service account
oc get sa -n openshift-operators | grep patterns
```

--------------------------------

### ArgoCD Git Tag Detection and Sync

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

This example demonstrates the process of tagging a release and pushing it to GitHub, which is then automatically detected by ArgoCD for synchronization and deployment. It also shows how to view the status of applications within ArgoCD.

```bash
# Tag release
git tag v1.0.0
git push github v1.0.0

# ArgoCD detects new tag and syncs
# View status
oc get applications -n openshift-gitops
```

--------------------------------

### Install Azure CLI in Execution Environment YAML

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/explanation/concepts.md

Configure the execution-environment.yml file to install Azure CLI during the build process using the prepend_base stage. This example demonstrates how to add yum repositories and install system packages via the additional_build_steps directive. Uncomment these lines to enable Azure CLI installation in your Execution Environment image.

```yaml
additional_build_steps:
  prepend_base:
    - >
      RUN $PKGMGR install -y dnf &&
      rpm --import https://packages.microsoft.com/keys/microsoft.asc &&
      dnf -y install -y https://packages.microsoft.com/config/rhel/9.0/packages-microsoft-prod.rpm &&
      $PKGMGR -y install azure-cli
```

--------------------------------

### Common Makefile Commands for Support and Deployment

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

A set of common Makefile commands used for various support, deployment, and development tasks within the Ansible Toolkit. This includes initiating full deployments, setting up the development environment, performing status checks, cleaning up deployments, and accessing help documentation.

```bash
# Full deployment
make end2end-deployment

# Development setup
make setup-gitea

# Status checks
make cluster-info
make check-prerequisites

# Cleanup
make end2end-cleanup

# Documentation
make end2end-help
make onboard-help
```

--------------------------------

### Ansible Toolkit Onboarding Commands

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Commands to guide users through the onboarding process for new or existing projects within the Ansible Toolkit. This includes options for creating new projects, onboarding existing ones, and checking the status of the onboarding process.

```bash
# New Project Onboarding
make onboard-new-project PROJECT_NAME=name

# Existing Project Onboarding
make onboard-existing-project PROJECT_NAME=name

# Onboarding Status
make onboard-status PROJECT_NAME=name
```

--------------------------------

### Install with Global Values

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/quarkus-reference-app/VALUES-README.md

Demonstrates how to install the Quarkus reference application using Helm with the global values file. This sets the base configuration for the application across all environments.

```bash
helm install quarkus-reference-app ./charts/all/quarkus-reference-app \
  -f values-global.yaml
```

--------------------------------

### Install Sealed Secrets Operator with Helm (Bash)

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/TROUBLESHOOTING-COMPREHENSIVE.md

Adds the Bitnami Sealed Secrets Helm repository and installs the operator into the 'kube-system' namespace. This is a solution for Issue 14.

```bash
# Install via OperatorHub or Helm
helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets
helm install sealed-secrets sealed-secrets/sealed-secrets \
  -n kube-system
```

--------------------------------

### Install MkDocs Dependencies and Build Docs

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/how-to/build-docs-locally.md

This snippet covers setting up a Python virtual environment, installing MkDocs dependencies from a requirements file, and building the documentation site using MkDocs. It assumes Python 3.9+ and pip are installed. The output is a built documentation site in the 'site/' directory.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r mkdocs.yml/requirements.txt
mkdocs build -f mkdocs.yml/mkdocs.yml
```

--------------------------------

### Debug Ansible Collection Installation

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/TROUBLESHOOTING-COMPREHENSIVE.md

Provides commands to debug Ansible collection installations. This includes verifying the physical presence of the collection files in the expected directory, checking the installed version of a specific collection, and testing if a module within the collection can be imported and used.

```bash
# Verify collection installation
ls -la ~/.ansible/collections/ansible_collections/rhvp/

# Check collection version
ansible-galaxy collection list rhvp.cluster_utils

# Test collection import
ansible -m debug -a "msg={{ lookup('rhvp.cluster_utils.version') }}"
```

--------------------------------

### Existing Project Onboarding - Bash

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

Workflow for integrating an existing project into the validated patterns toolkit. Creates a .validated-patterns subdirectory, copies toolkit files, preserves git history, and sets up Gitea for development.

```bash
# Onboard existing project
make onboard-existing-project PROJECT_NAME=my-project
```

--------------------------------

### Ansible Toolkit Support Commands

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/ONBOARDING.md

A collection of commands to assist users in troubleshooting and obtaining information about their Ansible Toolkit setup. This includes commands for viewing cluster information, checking prerequisites, and accessing help documentation for deployment and onboarding.

```bash
# Show cluster info
make cluster-info

# Show onboarding help
make onboard-help

# Check prerequisites
make check-prerequisites

# View deployment workflow
make end2end-help

# View logs
oc logs -n openshift-gitops -f
```

--------------------------------

### Deploy Pattern using Ansible Playbook

Source: https://github.com/tosin2013/validated-patterns-ansible-toolkit/blob/main/docs/END-USER-GUIDE.md

This bash script demonstrates the quick start deployment process. It involves logging into an OpenShift cluster, cloning the repository, editing configuration files, and executing an Ansible playbook to deploy a specified pattern. The playbook relies on parameters like pattern name and Git URL.

```bash
# 1. Login to OpenShift
oc login <cluster-url>

# 2. Clone repository
git clone https://github.com/tosin2013/validated-patterns-ansible-toolkit.git
cd validated-patterns-ansible-toolkit

# 3. Edit configuration
vi quarkus-reference-app/values-global.yaml
vi quarkus-reference-app/values-hub.yaml

# 4. Deploy pattern
ansible-playbook ansible/playbooks/deploy_with_operator.yml \
  -e validated_patterns_pattern_name=quarkus-reference-app \
  -e validated_patterns_git_url=https://github.com/tosin2013/validated-patterns-ansible-toolkit.git

# 5. Monitor deployment
oc get applications -n openshift-gitops -w
```