Skip to content

gitops-repository Directory Structure

This is the annotated directory tree of the real gitops-repository/clusters/ directory. Every file and folder is explained.

Full Tree (using "example-dev" as the example cluster)

Key File Types

.hydra/ under a root app

Hydra may create a .hydra/ directory inside each root app folder (next to Chart.yaml). It holds local cache data such as serialized Helm render inputs and rendered manifests under .hydra/cache/helm/. This directory is not part of what ArgoCD applies; teams typically add .hydra/ to .gitignore if they do not want cache files in Git.

Chart.yaml

Every root app has a Chart.yaml that declares which chart from charts-repository/ it uses:

apiVersion: v2
name: cluster-infra
version: 0.1.0
dependencies:
  - name: cluster-infra
    version: "*"
    repository: "file://../../../../charts-repository/apps/cluster-infra/root/dev"

The repository: "file://..." path is a symlink or relative path to the shared chart in charts-repository/.

values.yaml

Each level has its own values.yaml with settings that get merged. Example cluster-level values:

global:
  hydra:
    path: apps/cluster-infra/root/dev
    stage: dev
    repository: https://github.com/org/example-gitops-repo
    revision: main

Important: Use global.hydra.type to mark hierarchy levels (group/context/cluster/root-app/child-app). You can stop parent lookup with global.hydra.parent: false on a level.

templates/apps.yaml

The root app template that generates child ArgoCD Applications. This is the heart of the App of Apps pattern — one template creates all the child applications.

*.sops.yaml

Encrypted secret files. They look like normal YAML but with encrypted values. Only decryptable with the correct age or GPG key.

backup-*.sops.yaml

Backed-up secrets. These are runtime-generated secrets (like TLS certificates from Let's Encrypt) that were saved with hydra gitops backup create before an uninstall. They're stored with suspend: true so the SOPS operator doesn't process them — Hydra manages their lifecycle directly.

How Hydra Reads This Structure

When you run hydra gitops apply example-dev.**:

  1. Hydra finds example-dev under clusters/test/example-dev/
  2. It merges values from test/values.yaml → example-dev/values.yaml → in-cluster/values.yaml
  3. For each root app (argocd, cluster-infra, demo-infra, demo), it adds the root app's values.yaml
  4. It renders the Helm chart referenced in Chart.yaml
  5. The rendered templates produce Kubernetes resources that get applied to the cluster

How to Identify Cluster App IDs

The directory structure maps directly to Hydra App IDs:

Directory path App ID
clusters/test/example-dev/in-cluster/argocd/ in-cluster.argocd
clusters/test/example-dev/in-cluster/cluster-infra/ in-cluster.cluster-infra
child app cert-manager under cluster-infra in-cluster.cluster-infra.cert-manager
clusters/test/example-dev/in-cluster/demo/ in-cluster.demo

Next Steps