{"id":20155329,"url":"https://github.com/redhat-cop/gitops-standards-repo-template","last_synced_at":"2026-03-04T21:03:01.181Z","repository":{"id":206109722,"uuid":"712453980","full_name":"redhat-cop/gitops-standards-repo-template","owner":"redhat-cop","description":"Standard structure for an OpenShift multi-cluster day 2 configurations","archived":false,"fork":false,"pushed_at":"2024-04-22T11:49:12.000Z","size":106,"stargazers_count":23,"open_issues_count":9,"forks_count":10,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-01-13T12:43:45.936Z","etag":null,"topics":["container-cop"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-cop.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-31T13:58:55.000Z","updated_at":"2024-12-24T09:48:00.000Z","dependencies_parsed_at":"2023-12-15T21:39:17.480Z","dependency_job_id":"bdd5a40f-cf5b-4482-8f84-90904349b238","html_url":"https://github.com/redhat-cop/gitops-standards-repo-template","commit_stats":null,"previous_names":["redhat-cop/gitops-standards-repo-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgitops-standards-repo-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgitops-standards-repo-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgitops-standards-repo-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fgitops-standards-repo-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-cop","download_url":"https://codeload.github.com/redhat-cop/gitops-standards-repo-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241596244,"owners_count":19988041,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container-cop"],"created_at":"2024-11-13T23:31:38.573Z","updated_at":"2026-03-04T21:03:01.137Z","avatar_url":"https://github.com/redhat-cop.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitOps standard folder layout for OpenShift multi-cluster day-two configurations\n\nAs the title suggest this standard layout is laser focused on addressing the infrastructure configurations (a.k.a. day-two) for a multi-cluster deployment of OpenShift.\n\nTL;DR: jump to the [getting started](#getting-started-with-this-repo) section.\n\n## Repo Structure\n\nThese are the main folders:\n\n![Folders](.docs/media/folders.png \"Folders\")\n\n### Components\n\nThis folder contains all of the root pieces of configurations, these are sometime also called structural part of the configuration, as opposed to the parametric part that depends on groups and clusters. Each piece of configuration resides in its own subfolder. These components should never derive from anything (i.e. their resources and components lists in the `kustomization.yaml` file are empty).\n\n![Components](.docs/media/components.png \"Components\")\n\nFor more examples and starter configurations for components, see the [Gitops Catalog](https://github.com/redhat-cop/gitops-catalog).\n\n### Groups\n\nThis folder contains common pieces of configurations that can be applied to a group of clusters. Groups can capture concepts like the purpose of the cluster (lab,non-prod, prod), the geography of the cluster (west, east, dc1, dc2), the security profile of the cluster (pci, non-pci, connected, disconnected) etc...\n\nGroups are designed to be composable. So, based on the example groups from above, one should be able to express that a cluster belongs to the non-prod, east, pci groups.\n\nComposition of groups is possible because groups are defined as kustomize [components](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/components/):\n\n```yaml\napiVersion: kustomize.config.k8s.io/v1alpha1\nkind: Component\n```\n\nThe `all` group almost always exists and it captures the configuration that goes in every cluster.\n\nEach group has it own folder. Within this folder, we can find two things: \n\n- A set of folders containing the group-specific overlays over some set of components.\n- A root level kustomization that generates the ArgoCD applications for this group, using the [argocd-app-of-app](.helm/charts/argocd-app-of-app/) helm chart. See the [all group](./groups/all/kustomization.yaml) for example.\n\n![Groups](.docs/media/groups.png \"Groups\")\n\nIn this example, in green you can see the overlays over one component, while in red you can see the resources needed to generate the Argocd Applications for this group.\n\n### Clusters\n\nThis folder contains the cluster-specific configurations. As for groups it is made of two parts:\n\n- A set of folders containing the cluster-specific overlays over some set of components.\n- A root level kustomization that generates the ArgoCD applications for this group, using the [argocd-app-of-app](.helm/charts/argocd-app-of-app/) helm chart. This kustomization must import the correct groups for this cluster, here is an example:\n\n```yaml\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\n\ncomponents:\n  - ../../groups/all\n  - ../../groups/non-prod\n  - ../../groups/geo-east\n```\n\nSee also the [hub cluster](./clusters/hub/kustomization.yaml) for example\n\n## Design Decisions\n\nIn no particular order, here are the design decisions that guides us to this current folder structure.\n\n- ArgoCD Applications for the [App of App pattern](https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/#app-of-apps-pattern) are generated via a Helm chart. This was chosen over the ApplicationSet approach. The reason of this choice is that The ApplicationSet controller seems a bit unstable and that helm charts offer mode flexibly.\n- Kustomize is the primary templating mechanism, if one needs to use helm charts, that is still possible via the Kustomize [HelmChartInflaterGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_helmchartinflationgenerator_). The reason of this choice are that Kustomize is easy to pick up in general so starting with kustomize is easier for new users. Also having kustomize at the top level provides homogeneity. This without losing flexibly as one can always use helm charts. \n- Groups of clusters a modeled via Kustomize components, this way they can be composed as opposed to being inherited giving more flexibility.\n\n## Conventions\n\ncomponents names\n\nsync waves\n\n## Getting started with this repo\n\nPress the `Use This Template` button at the right top corner of this page and follow the github instructions to create a detached copy of this repo.\n\nOnce you have a copy of this repo in your organization, you have to seed your Hub cluster to point to this repo.\n\nTo do so you can simply run this commands, however you might want to implement these steps in different ways in your environment:\n\n```sh\nexport gitops_repo=\u003cyour newly created repo\u003e\nexport cluster_name=\u003cyour hub cluster name, typically \"hub\"\u003e\noc apply -f .bootstrap/subscription.yaml\noc apply -f .bootstrap/cluster-rolebinding.yaml\noc apply -f .bootstrap/argocd.yaml\nenvsubst \u003c .bootstrap/root-application.yaml | oc apply -f -\n```\n\nNote: for pedagogical reason this repo contains some example of components, groups and clusters, you will have to likely remove these examples and start adding the configurations you actually need.\n\n### Local tools \u0026 setup\n\nIn order to work with this repo effectively, you'll need the following tools installed locally:\n\n- [oc](https://docs.openshift.com/container-platform/4.14/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli)\n- [helm](https://helm.sh/docs/intro/install/)\n- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/binaries/)\n\n### Debugging\n\nMost debugging and troubleshooting can be done by rendering the root app of apps locally using helm \u0026 kustomize. Here are a few examples.\n\nWhich applications are currently included in the `hub` cluster?\n\n```bash\nkustomize build clusters/hub/ --enable-helm\n```\n\nWhich applications are part of the `non-prod` group?\n\n```bash\nkustomize build groups/non-prod/ --enable-helm\n```\n\n## Use cases\n\n### Pinning and Promotions\n\nWe use the concept of git repository pinning to version and then promote configurations. Pinning can be done via tagging or directly referencing commit SHAs.\nPromoting always consists of changing the pinned version. Depending on where you pin you can manage to promote a single configuration in a individual cluster or all of the configurations in a group for individual clusters ir all of the configurations for a cluster ( and more combinations are even possible).\n\n#### Component configuration Pinning and Promotion\n\nTo pin a component to a specific version, use pinning when importing it in a cluster level or group level configuration. This will look like this in the values file for the cluster/group:\n\n```yaml\napplications:\n\n  cert-manager-operator:\n    annotations:\n      argocd.argoproj.io/compare-options: IgnoreExtraneous\n      argocd.argoproj.io/sync-wave: '5'\n    destination:\n      namespace: cert-manager\n    source:\n      path: components/cert-manager-operator\n      targetRevision: \u003cpin\u003e\n```\n\n\n#### group configuration pinning and promotion\n\nIn order to pin an entire group-level configuration for a given cluster, pin the component in the kustomization file, like this:\n\n```yaml\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\n\ncomponents:\n  - ../../groups/all\n  - https://github.com/raffaelespazzoli/gitops-std-repo/groups/non-prod?ref=v1.0.6\n  - ../../groups/geo-east\n\n```\n\n#### cluster configuration pinning and promotion\n\nIn order to version pin an entire cluster configuration, you need to do the pinning at the app of app root level. We have so far not talked about how the app of app so created, but the pinning would look like this:\n\n```yaml\napiVersion: argoproj.io/v1alpha1\nkind: Application\nmetadata:\n  name: root-applications\n  # You'll usually want to add your resources to the argocd namespace.\n  namespace: openshift-gitops\n  # Add this finalizer ONLY if you want these to cascade delete.\n  finalizers:\n    # The default behaviour is foreground cascading deletion\n    - resources-finalizer.argocd.argoproj.io\n    # Alternatively, you can use background cascading deletion\n    # - resources-finalizer.argocd.argoproj.io/background\n  # Add labels to your application object.\n  labels:\n    app-source: root\n    repo: cluster-config\nspec:\n  # The project the application belongs to.\n  project: default\n\n  # Source of the application manifests\n  source:\n    repoURL: ${gitops_repo}  # Can point to either a Helm chart repo or a git repo.\n    targetRevision: \u003cpin\u003e  # For Helm, this refers to the chart version.\n    path: clusters/${cluster_name}  # This has no meaning for Helm charts pulled directly from a Helm repo instead of git.\n...\n```\n\nagain using the `targetRevision` field.\n\n### how to bootstrap a newly create/registered cluster with gitops\n\n### how to pass cluster-level variables to all of the configurations\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fgitops-standards-repo-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-cop%2Fgitops-standards-repo-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fgitops-standards-repo-template/lists"}