Vp Refactor

Validated Pattern Refactor Skill

When to Use

• Developer has run patternizer init and asks "what do I fill in now?"
• Pattern deploys manually but fails when installed via the Validated Patterns Operator
• Preparing a pattern for Sandbox tier submission to validatedpatterns.io
• Upgrading an existing pattern from the old common/ submodule structure to Makefile-common
• Developer asks "is my pattern ready to submit?"
• Values files are incomplete or operators are not deploying correctly
• pattern-metadata.yaml is missing or incorrectly structured
• Secrets are committed to the repository or not using the correct file location

Instructions

This skill defines an audit process, not a tool wrapper. When activated, collect the required input from the developer, then work through the audit areas below in order. For each area, assess the current state, identify gaps, and provide specific remediation steps.

Do NOT use this skill when a developer is initializing a new pattern from scratch — use the patternizer skill instead.

Gotchas

• NEVER use OperatorHub.io metadata — use oc get packagemanifests on the target cluster to get the real operator names and channels
• values-secret.yaml must NEVER be committed to git — it contains real credentials. Only values-secret.yaml.template goes in the repo
• The VP Operator watches for changes to values-global.yaml — modifying it triggers a full reconciliation. Edit carefully
• Helm chart values.yaml files must not contain cluster-specific values — those go in values-global.yaml or values-<cluster>.yaml
• ArgoCD Application names must be unique across the cluster, not just the namespace — name collisions cause silent sync failures

Required Input

Before auditing, collect the following from the developer:

Audit Areas

Work through each area in order. Report findings as a pass/fail table at the end (see Output Format).

1. Post-Init Values File Completeness

Two files control all deployments. Both must be populated before ./pattern.sh make install will succeed.

values-global.yaml — mandatory field:

main.clusterGroupName is the topological router. ArgoCD uses this string to find the cluster-specific values file. The string must have a 1:1 match with a values-<string>.yaml filename.

main:
  clusterGroupName: hub   # targets values-hub.yaml

A mismatch causes catastrophic failure — ArgoCD injects no workloads and no error is reported until the sync times out.

values-<cluster>.yaml — three mandatory blocks in dependency order:

Verify all three blocks are present and that subscriptions: namespaces match entries in namespaces:, and applications: paths resolve to directories containing Chart.yaml.

See references/values-files-guide.md for the full schema and a minimal working example.

2. Operator Subscription Correctness

Catalog sources — pick the right tier:

Never use OperatorHub.io to find channel or CSV values — the cluster's internal catalog may lag or mirror different builds. Always query the cluster directly from the openshift-marketplace namespace:

# Step 1 — find package name and confirm source
oc get packagemanifests -n openshift-marketplace | grep <keyword>

# Step 2 — get the default channel
oc get packagemanifest <name> -n openshift-marketplace \
  -o jsonpath='{.status.defaultChannel}'

# Step 3 — get the startingCSV for that channel
oc get packagemanifest <name> -n openshift-marketplace \
  -o jsonpath='{.status.channels[?(@.name=="<channel>")].currentCSV}'

startingCSV is mandatory for GitOps immutability. Omitting it allows OLM to upgrade unpredictably — the same Git commit produces different cluster states at different times. It can also cause InstallPlan generation to fail, leaving the workload perpetually in a Pending state.

For each subscription entry, verify all four fields are present and exactly match cluster catalog output. See references/operator-discovery.md for the complete workflow with examples.

3. Charts Directory Structure

Minimum Helm chart structure — ArgoCD does not parse unstructured YAML directories. Every path: in applications: must resolve to a directory with these three components:

charts/hub/my-app/
├── Chart.yaml       ← REQUIRED: absence causes ArgoCD to reject directory entirely
├── values.yaml      ← REQUIRED: default variable declarations (overridden by global/cluster values)
└── templates/       ← REQUIRED: Kubernetes resource files (static YAML or Go templates)

applications: field-to-ArgoCD mapping:

Path resolution rule: path: charts/hub/my-app is correct. path: my-app will fail because ArgoCD resolves paths from the repository root, not from any subdirectory.

For each applications: entry, verify:

1. The path: directory exists in the pattern repo
2. Chart.yaml is present at that path
3. namespace: matches an entry in the namespaces: block
4. project: matches an existing ArgoCD AppProject

See references/charts-directory.md for the Chart.yaml field reference and common failure modes.

4. Secrets Model Compliance

Step 1 — Check for committed secrets (highest priority fix):

git log --all --full-history -- "*values-secret*"
git grep -l "password\|token\|secret\|key" -- "*.yaml" | grep -v "ExternalSecret\|SecretStore"

If values-secret.yaml appears in git history, it must be purged from history — not just deleted in the latest commit.

Step 2 — Verify --with-secrets was used at init:

Patterns requiring secrets need HashiCorp Vault + External Secrets Operator. Check whether the VP subscription definitions include ESO:

grep -r "external-secrets\|vault" values-*.yaml

If secrets are needed but ESO is absent, the pattern was initialized without --with-secrets. The values files will need Vault and ESO subscriptions added manually or the pattern should be re-initialized.

Step 3 — Verify values-secret.yaml location:

The make load-secrets target searches these paths in order:

1. ~/.config/validatedpatterns/values-secret-<pattern_name>.yaml ← required location
2. ~/.config/hybrid-cloud-patterns/values-secret-<pattern_name>.yaml

The file must never be inside the cloned repository directory. Moving it to ~/.config/validatedpatterns/ is mandatory, non-negotiable.

Step 4 — Verify the secrets flow works:

./pattern.sh make load-secrets

If this command fails to find the file, it means either the file is missing or it is in the wrong location. See references/secrets-management.md for the full Vault+ESO architecture and safe workflow.

5. VP Operator Compatibility

The VP Operator and the CLI (./pattern.sh make install) have distinct requirements. Test both paths separately.

Three required Operator form fields:

Critical Operator limitation: The VP Operator runs inside the cluster and has no access to the developer's local filesystem. It cannot run make load-secrets. If the pattern requires secrets:

• Deploy pattern components via the Operator UI
• Then authenticate locally and run ./pattern.sh make load-secrets separately

Verify Operator compatibility checklist:

# 1. Pattern repo is publicly accessible (Operator pulls directly from Git)
curl -s https://github.com/<your-org>/<pattern-name> | grep -c "repository"

# 2. Your fork URL differs from the upstream VP URL
grep -r "validatedpatterns/" values-*.yaml  # should show your fork, not upstream

# 3. Check Operator-created resources
oc get pattern -A
oc get application -n openshift-gitops

See references/vp-operator-guide.md for the full CLI vs Operator comparison and when to use each.

6. pattern-metadata.yaml Presence

pattern-metadata.yaml is the identity document for the pattern within the VP ecosystem. It is parsed by upstream aggregators, CI pipelines, and the VP website for indexing and catalog display.

patternizer init does not generate this file. Developers must create it manually at the repository root.

Consequences of absence:

• The pattern is invisible to the VP framework catalog
• Automated indexing cannot process the repository
• Any tier submission (Sandbox, Tested, Maintained) results in immediate rejection

Check:

ls -la pattern-metadata.yaml   # must exist at repo root

Known content requirements (from research):

• Formalized display name for the VP catalog
• Architectural description (what the pattern deploys and why)
• Targeted enterprise use cases (the business problems solved)
• Technical prerequisites (e.g. required vector databases, inference providers for LLM patterns)

(SCHEMA PENDING — RQ-6 partial: The exact YAML field names require inspection of upstream reference patterns. See references/pattern-metadata.md for the pending items and recommended upstream sources to check.)

If the file is missing, create it at the repo root based on the structure from the multicloud-gitops reference pattern.

7. Sandbox Tier Submission Checklist

Check these items directly against the VP tier requirements:

Required for Sandbox tier:

Not required for Sandbox but needed for Tested tier:

• Business use case with working demo
• Test plan (manual or automated) that passes at least once per quarter
• Publicly visible test results JSON file
• Implementation review by the VP team

8. Imperative Jobs Assessment

The imperative: section is an escape hatch for tasks that cannot be expressed as OLM subscriptions or Helm chart resources. ArgoCD deploys CronJobs in an imperative namespace that run Ansible playbooks inside the cluster.

Assess whether imperative jobs are needed:

If the developer has any of these after ./pattern.sh make install, they are candidates for the imperative: section:

• Shell scripts or oc commands run manually after install
• Vault unsealing steps
• Certificate distribution tasks
• RHACM API calls for multi-cluster configuration
• AAP controller registration tasks
• Bare-metal network configuration

If imperative jobs are present, verify these four requirements:

1. Jobs defined as a YAML list (not a hash):

# CORRECT — list preserves order for Helm rendering
clusterGroup:
  imperative:
    jobs:
      - name: bootstrap-vault
        playbook: ansible/playbooks/bootstrap-vault.yaml
      - name: distribute-ca
        playbook: ansible/playbooks/distribute-ca.yaml

YAML hashes lose ordering when parsed by Helm. Execution order is critical for bootstrapping sequences.

2. Playbooks exist in ansible/playbooks/:

ls ansible/playbooks/

The default container image (registry.redhat.io/ansible-automation-platform-22/ee-supported-rhel8:latest) expects playbooks at this path.

3. All playbooks are strictly idempotent: Jobs run every 10 minutes by default (*/10 * * * *). Non-idempotent playbooks will overwrite configurations, exhaust API rate limits, or destabilize the cluster on each cycle. Verify every playbook checks state before acting.

4. Vault unsealing (if Vault is used) runs on a 9-minute schedule:

# Vault unsealing uses a tighter schedule than the default 10-min cycle
schedule: "*/9 * * * *"

See references/imperative-jobs.md for the full CronJob architecture and configurable options (timeout, serviceAccountName, Ansible verbosity).

Output Format

Present audit results as a pass/fail table with a tier-readiness summary:

VP Pattern Refactor Audit — Pattern: <pattern-name>
──────────────────────────────────────────────────────────
 #  Area                            Status  Notes
 1  Values file completeness        FAIL    values-hub.yaml missing subscriptions: block
 2  Operator subscriptions          FAIL    cert-manager channel "stable-v1" not found on OCP 4.17
 3  Charts directory structure      PASS    All application paths resolve to valid Helm charts
 4  Secrets model compliance        FAIL    values-secret.yaml committed to repo — must be removed
 5  VP Operator compatibility       SKIP    Research pending — RQ-5
 6  pattern-metadata.yaml           FAIL    File missing from repository root
 7  Sandbox tier checklist          PARTIAL README present, no architecture diagram
 8  Imperative jobs                 N/A     Pattern is fully declarative
──────────────────────────────────────────────────────────
 Result: 3 FAIL, 1 PASS, 1 PARTIAL, 1 SKIP (research pending), 1 N/A
 Sandbox tier readiness: NOT READY (fix #4, #6, and #7 first)
 Priority fixes: #4 (secrets in repo), #6 (pattern-metadata.yaml), #1 (subscriptions block)

Escalation

When audit findings reveal deeper issues:

1. Pattern won't initialize → Use the patternizer skill for init and upgrade guidance
2. Operator not deploying after subscription is correct → Check oc get csv -A and oc get installplan -A
3. ArgoCD Application stuck in OutOfSync → Check oc get app -n openshift-gitops and inspect sync errors
4. Secrets not injecting → Review VP Secrets Management docs
5. Sandbox tier questions → See VP contribution guide and tier requirements

Best Practices

• Run this audit immediately after patternizer init, before attempting ./pattern.sh make install
• Address Sandbox tier checklist items (area 7) in parallel with technical fixes — the README and diagram are quick wins that unblock tier review
• Test with the VP Operator (area 5) separately from ./pattern.sh — they have different requirements