Shared Configuration Repository

Share configuration settings across GitOps Runtimes

A Codefresh account with a Hosted or a Hybrid GitOps runtime can store configuration manifests for account-level resources in a Git repository. This repository, the Shared Configuration Repository, can be shared with other GitOps Runtimes in the same account, avoiding the need to create and maintain different configuration manifests for every GitOps Runtime. At the same time, you also have the flexibility to store resources unique to specific Runtimes without affecting other Runtimes.

When is it created?

The Shared Configuration Repository (internally ISO/iso) is created on installing the first Hosted or Hybrid GitOps Runtime in the account. See GitOps Runtimes & Shared Configuration Repos.

Benefits

• Centralized Runtime configuration management
  With the Shared Configuration Repository, you can store configuration manifests for account-level resources in a centralized location. The Git repository is accessible to all GitOps Runtimes within the same Codefresh account, ensuring that account-level resources are consistently deployed and managed across all environments.

• Runtime-specific configuration
  With the Shared Configuration Repository, you can create subdirectories for different GitOps Runtimes, and place configuration manifests that are only applied to specific GitOps Runtimes. You have fine-grained control over the configuration of individual Runtimes without affecting others.

See Shared Configuration Repo structure

GitOps Runtimes & Shared Configuration Repos

• Hosted GitOps Runtimes
  As part of the setup for a Hosted GitOps runtime, Codefresh creates the Shared Configuration Repository in the selected organization, together with the default Git Source repo. See Connect Git provider in Hosted GitOps setup.

• Hybrid GitOps Runtimes
  When you install the first Hybrid GitOps runtime for an account, you are required to define the Shared Configuration Repo as part of setting up your Git account. See Installing Hybrid GitOps Helm Runtime installation: Set up Git provider.

Shared Configuration Repo URL formats

When defining the Shared Configuration Repository for the account, you have the option to specify a path, a branch, or both, within the repository URL. This allows for flexibility in targeting specific directories or branches in the repository.

<repo_url>.git[/<path>][?ref=<branch>]

where:

• <repo_url>.git is required and is the repository URL. This is the standard URL format which references the root of the default branch in the repository.
  Example: https://github.com/codefresh-io/our-isc.git

• <path> is optional, and points to a specific path within the repository. Use <path> if you want your configuration files within a subdirectory.
  Example: https://github.com/codefresh-io/our-isc.git/some/path

• <branch> is optional, and references a specific branch in the repository.
  Example: https://github.com/codefresh-io/our-isc.git?ref=isc-branch

Combining both a path and a branch allows more granular control.
Example: https://github.com/codefresh-io/our-isc.git/some/path?ref=isc-branch.

Location of the Shared Configuration Repo

You can see the URL of the Shared Configuration Repo for your Runtime in the Organization Information page.

Examples of configuration definitions in Shared Repo

Here are a few types of configuration definitions stored in the Shared Configuration Repository:

• In-cluster and managed clusters
• Git Sources
• Integrations between Codefresh and third-parties for GitOps
• OAuth2 authentication applications

Shared Configuration Repo structure

Below is a representation of the structure of the repository with the shared configuration. See a sample repo.

├── resources <───────────────────┐
│   ├── all-runtimes-all-clusters │
│   │   ├── cm-all.yaml           │
│   │   └── subfolder             │
│   │       └── manifest2.yaml    │
│   ├── control-planes            │
│   │   └── manifest3.yaml        │
│   ├── runtimes                  │
│   │   ├── runtime1              │
│   │   │   └── manifest4.yaml    │
│   │   └── runtime2              │
│   │       └── manifest5.yaml    │
│   └── manifest6.yaml            │
└── runtimes                      │
    ├── runtime1                  │ # referenced by "production-isc" argo-cd application, applied to the cluster by "cap-app-proxy"
    │   ├── in-cluster.yaml      ─┤ #     manage `include` field determines which dirs/files to sync to cluster
    │   └── remote-cluster.yaml  ─┤ #     manage `include` field to decide which dirs/files to sync to cluster
    └── runtime2                  │ # referenced by "staging-isc" argo-cd application, applied to the cluster by "cap-app-proxy
        └── in-cluster.yaml      ─┘ #     manage `include` field determines which dirs/files to sync to cluster

resources directory

The resources directory holds the resources shared by all clusters managed by the GitOps Runtimes:

• resources/all-runtimes-all-clusters: Every resource manifest in this subdirectory is applied to all the GitOps Runtimes in the account, and to all the clusters managed by those Runtimes. In the above example, manifest2.yaml is applied to both runtime1 and runtime2.
• resources/control-planes: Optional. When defined, every resource manifest in this subdirectory is applied to each Runtime’s in-cluster.
  Config map resources for example, when committed to this subdirectory, are deployed to each Runtime’s in-cluster.
• resources/runtimes/<runtime_name>: Optional. Runtime-specific subdirectory. Every resource manifest in a runtime-specific subdirectory is applied to only the GitOps Runtime defined by <runtime_name>. In the above example, manifest4.yaml is applied only to runtime1, and manifest5.yaml is applied only to runtime2.

runtimes directory

The runtimes directory includes subdirectories specific to each GitOps Runtime installed in the cluster. Every subdirectory always has an in-cluster.yaml, and optionally, application manifest YAMLs for other clusters. The runtimes/<runtime1> subdirectory for example, includes the in-cluster.yaml, and a remote-cluster.yaml for the remote cluster also managed by the same Runtime.

Example application manifest for in-cluster.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  labels:
    codefresh.io/entity: internal-config
    codefresh.io/internal: 'true'
  name: in-cluster
spec:
  project: default
  source: 
    repoURL: <account's-shared-config-repository>
    path: resources # or shared-config/resources
    directory:
      include: '{all-runtimes-all-clusters/*.yaml,all-runtimes-all-clusters/**/*.yaml,runtimes/<runtime_name>/*.yaml,runtimes/<runtime_name>/**/*.yaml,control-planes/*.yaml,control-planes/**/*.yaml}'
      recurse: true
  destination:
    namespace: <runtime_name>
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      allowEmpty: true
      prune: true
      selfHeal: true
    syncOptions:
      - allowEmpty=true

Git Source application per Runtime

In addition to the application manifests for GitOps Runtimes in the Shared Configuration Repository, every GitOps Runtime has a Git Source application that references runtimes/<runtime-name>.

This Git Source application creates an application manifest with the <cluster-name> for every cluster managed by the GitOps Runtime. The include field in the <cluster-name> application manifest determines which subdirectories in the resources directory are synced to the target cluster.

Shared Configuration Repo as Runtime application

You can view and monitor all resources in the Shared Configuration Repo as any other Argo CD application in the GitOps Apps dashboard’s Current State tab.

Select the Runtime ISC Application option from the Runtime’s context menu.

Reset Shared Configuration Repo

As a Codefresh admin, you can reset the repo defined for your account if the URL is either incorrect or missing, or if there are no active GitOps Runtimes.

Conditions for reset of Shared Repo

• Incorrect/missing URL
  Mandatory when Codefresh notifies you through the UI that the Shared Configuration Repo URL is either incorrect or missing.

  • Incorrect URL
    The Shared Config Repo details provided during installation in Account Setup are incorrect. Codefresh could not connect to the Shared Repo with the details provided.
  • Undefined URL
    You installed the GitOps Runtime through a script or an automated mechanism without providing the URL to the Shared Configuration Repository.

• No active Runtimes
  If Codefresh has already validated the existing Shared Configuration Repository, meaning that at least one GitOps Runtime successfully connected to it, you cannot change the Shared Configuration Repo URL. To do so, you must contact Codefresh Support.

  Otherwise, you can reset the Shared Config Repo URL only after uninstalling all the GitOps Runtimes in your account. This option is useful when moving from a temporary account, for example, a POV account, to your organization’s official account to reset the URL.

Reset Shared Config Repo via CLI

Before you begin

• Make sure you have no active GitOps Runtimes in your account

How to

1. Run cf config update-gitops-settings --shared-config-repo <shared_repo_url>
   where:
   <shared_repo_url> is the new URL for the Shared Configuration Repository, optionally including a path, branch or both.
2. When prompted, select the Git provider.
3. Confirm to create the Shared Configuration Repo.

Use case: Integration resources for Runtimes

When creating a new GitOps Integration resource, such as a container registry integration for example in the Codefresh UI, you can define the GitOps Runtimes to which to apply that resource. The app-proxy saves the resource in the correct location in the Shared Configuration Repo, and updates the relevant Argo CD Applications to include it.

Use case: Create application for distribution across all GitOps Runtimes

In this scenario, you want to distribute an application configuration to all GitOps Runtimes within your Codefresh account. Storing the application manifest in the resources/all-runtimes-all-clusters directory of the Shared Configuration Repository makes it automatically accessible to all the GitOps Runtimes in the account and to all the clusters managed by those Runtimes.

Here’s how to do this with the Shared Configuration Repo:

1. Create or update the application manifest in the resources/all-runtimes-all-clusters directory of the Shared Configuration Repository.
2. Specify the desired configuration settings and resources required for the application in the manifest file.
3. Save and commit the changes to the Git repository.

Related articles

Hosted GitOps Runtime installation
Hybrid GitOps Runtime installation