Shared Configuration Repository

Share configuration settings across GitOps Runtimes

Shared Configuration Repository

A Codefresh account with 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.

Watch this video for an overview: Shared Configuration Repository

When is it created?

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

IMPORTANT
Only Codefresh account administrators should have access to the Shared Configuration Repository. Its content is automatically generated and maintained by Codefresh.
While it is useful to understand its structure, we recommend using it for reference only, and NOT for making commits or manual changes.

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.

NOTE
In the documentation, we use Shared Configuration Repository or Shared Config Repo for clarity. In code samples and internal references, it is represented as isc.

Examples of configuration definitions in Shared Repo

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

See Shared Configuration Repo structure.

GitOps Runtimes & Shared Configuration Repos

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.

Shared Configuration Repo URL

Shared Configuration Repo URL

Shared Configuration Repo structure

Below is a representation of the structure of the repository with the shared configuration in the GitOps Runtime designated as the Configuration Runtime.


├── resources <───────────────────┐
│   ├── all-runtimes-all-clusters │
│   │   ├── cm-all.yaml           │
│   │   └── subfolder             │
│   │   └── manifest3.yaml        │
│   │   └── promotion-workflows   │ # stores promotion workflow manifests available to all runtimes
│   │       └──  smoke-tests.yaml │
│   ├── runtimes                  │
│   │   ├── runtime1              │
│   │   │   └── manifest4.yaml    │
│   │   └── runtime2              │
│   │       └── manifest5.yaml    │
│   └── manifest6.yaml            │
└── app-projects                  │
└── configurations                │ # syncs to cluster by runtimes designated as Configuration Runtime
│   ├── products                  │ #    stores product manifests with all product settings except assigned applications
│   │   └── loans.yaml            │
│   ├── promotion-flows           │ #    stores promotion flow manifests with promotion orchestration settings 
│   │   ├── base-flow.yaml        │
│   │   └── hot-fix.yaml          │
│   └── promotion-policies        │ #    stores promotion policy manifests for products/environments with promotion workflows & promotion action  
│   │   ├── base-flow.yaml        │
│   │   └── prod-pr.yaml          │
│   │   └── loan-policy.yaml      │
│   └── promotion-templates        │ #    stores promotion template manifests for products with source info for version & properties to promote
│       └── demo-template.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 contains the resources shared by all clusters managed by GitOps Runtimes.

Shared Configuration Repo Description
resources/all-runtimes-all-clusters Contains resource manifests 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/all-runtimes-all-clusters/promotion-workflows Stores manifests of Promotion Workflows, available to all Runtimes in the account.
See Promotion Workflows.
resources/control-planes Optional. When defined, applies every resource manifest 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/app-projects Contains application project resources which control deployment destinations for applications.
resources/configurations Contains platform-level resources which are Runtime-agnostic, essential for functionality related to product and promotion entities in GitOps.
resources/configurations/products Contains manifests of product entities. All settings including source location for application version, promotable properties, promotion flows with trigger conditions if defined are saved. Note that applications assigned to products are not saved in the manifest. Product manifests are available to users with the required ABAC permissions.
See Product Settings and Product YAML.
resources/configurations/promotion-flows Contains manifests of promotion flows with the trigger and target environments, and custom promotion policy settings, if any.
See Promotion Flow configuration and Promotion Flow YAML.
resources/configurations/promotion-policies Contains manifests of promotion policies with the Pre- and Post-Action Workflows if defined, the Promotion Action, and target products and environments.
See Promotion Policy configuration and Promotion Policy YAML.
resources/configurations/promotion-templates Contains manifests of promotion templates defining the sources for the release version and the properties to be promoted.
See Promotion Template configuration and Promotion Template YAML.
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.

ISC (Shared Runtime Configuration repo) as Application

ISC (Shared Runtime Configuration repo) as Application

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.

Notification for missing/incorrect Shared Configuration Repository

Notification for missing/incorrect 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.

TIP
You can then monitor these applications in the GitOps Apps dashboard, and drill down to each application in the GitOps Apps dashboard.

GitOps Runtime essentials
Install GitOps Runtime
Install GitOps Runtime alongside Community Argo CD
Monitoring GitOps Runtimes
Managing GitOps Runtimes Managing Git Sources in GitOps Runtimes
Managing external clusters in GitOps Runtimes