development-gitops-argo-cd-3darch/references/cogarchhubgitops-reference.md

CogArchHubGitOps — Reference Implementation

The concrete instance of every pattern in this skill. Read when working in CogArchHubGitOps/ specifically, or as a worked example when standing up a new GitOps repository from the generic rules.

The generic rules live in SKILL.md and the other reference files; this file records only what is specific to this repository.

---

1. Repositories

CogArchHubGitOps/              ← target repository (the Copier template + answer files)
CogArchHubGitOps-code-agent/   ← code-agent repository (skills and agent tooling)

Work described by this skill lands in the target repository. Deployed environments are rendered copies of it.

---

2. Layout

CogArchHubGitOps/
├── copier.yaml
├── cluster/
│   ├── argocd/
│   │   ├── application.yaml.jinja                       # 000-root app-of-apps
│   │   ├── {{ '200-operators' if … }}/
│   │   ├── {{ '300-configuration' if … }}/
│   │   ├── {{ '400-databases' if … }}/
│   │   ├── {{ '700-advantage-mcp' if … }}/
│   │   └── {{ '800-applications' if … }}/
│   └── resources/
│       └── <mirrored conditional directories>/
└── <env>/
    └── copier-answers.yaml

cluster/argocd/application.yaml.jinja is the root app named 000-root. It watches cluster/argocd/ recursively and creates every child Application it finds.

---

3. Bands in use

Band	Domain	Concrete contents
000	Root	000-root app-of-apps
200–299	Operators	External Secrets Operator (ESO), CloudNativePG (CNPG), Redis
300–399	Cluster configuration	ClusterSecretStore and related config
400–499	Databases	PostgreSQL clusters, Redis clusters
700–799	Advantage / MCP	MCP servers, AI agent workloads
800–899	Platform applications	notification, integration, agent-service

ESO occupies a contiguous sub-group inside the 2xx band — operator group, subscription, and configuration each take their own number (210, 213, 215), so a related set stays readable in a sorted directory listing. Follow the same grouping habit for new operators.

---

4. Feature flags

Variable	Gates
operators.is_enabled	The whole 200-operators band
operators.eso_is_enabled	ESO operator group, subscription, configuration
operators.cnpg_is_enabled	CNPG operator group and subscription
operators.redis_is_enabled	Redis operator group and subscription
configuration.is_enabled	The whole 300-configuration band
configuration.cluster_secret_store_is_enabled	ClusterSecretStore
databases.is_enabled	The whole 400-databases band
advantage_mcp.is_enabled	The whole 700-advantage-mcp band
applications.is_enabled	The whole 800-applications band

Sub-flags are named <sub>_is_enabled and live flat under the domain object — operators.eso_is_enabled, not operators.eso.is_enabled. Keep new flags consistent with that shape.

---

5. ArgoCD conventions

• ArgoCD runs in the openshift-gitops namespace (OpenShift GitOps operator), so every Application sets metadata.namespace: openshift-gitops.
• spec.project is default.
• spec.destination.server is https://kubernetes.default.svc (in-cluster).
• prune: true and selfHeal: true are on for all apps.

---

6. Application global settings

applications.global in each answer file provides the settings shared by all 8xx services:

applications:
  global:
    is_internal: "false"
    enable_instana: "false"
    ca_secret_name: ca-secret
    ca_env: <env-name>
    maintenance: "false"
    host: <public-hostname>
    ca_host: <internal-hostname>
    suffix_url: <path-suffix>
    node_selector_app: <node-label>
    mongo:
      host: <mongodb-host>
      port: "27017"
      user: <mongodb-user>
    redis:
      host: <redis-host>
      port: "6379"
      max_retries: "3"
    neo4j:
      url: <neo4j-bolt-url>
      user: <neo4j-user>

The datastore blocks (mongo, redis, neo4j) carry connection coordinates only. Credentials come from ESO-managed secrets at runtime, which is why ca_secret_name and the ClusterSecretStore in the 3xx band are prerequisites for the 8xx band to work at all.

is_internal, enable_instana, and maintenance are quoted strings, not YAML booleans — they reach the Helm chart as strings. Feature flags in the same file are real booleans. See environments.md §4.

---

7. Private registry

Workload images pull from a private registry using the pre-existing secret storage-images:

imagePullSecrets:
  - name: "storage-images"

The secret is expected to exist in the target namespace already; it is not created by these templates. A new namespace therefore needs the secret provisioned before its first sync, or pods stall on ImagePullBackOff.

---

8. Ordering dependencies

The bands are numbered so a full bootstrap converges in ascending order:

1. 2xx operators install the CRDs everything else depends on (ESO, CNPG, Redis).
2. 3xx configuration creates the ClusterSecretStore that supplies secrets.
3. 4xx databases create instances using the operators' CRDs.
4. 7xx / 8xx workloads consume the databases and secrets.

ArgoCD does not enforce this ordering — the app-of-apps creates all children at once and each syncs independently. The numbering is a convention that makes the intended order legible, and failing apps in a fresh cluster usually resolve themselves once the band they depend on has finished syncing. Do not add sync-waves to force ordering without discussing it first; retry plus eventual consistency is the assumed model here.