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 asisc
.
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
- Manifests for promotion entities:
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 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.
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.
- Incorrect URL
-
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
- 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. - When prompted, select the Git provider.
- 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:
- Create or update the application manifest in the
resources/all-runtimes-all-clusters
directory of the Shared Configuration Repository. - Specify the desired configuration settings and resources required for the application in the manifest file.
- 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.
Related articles
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