Improve this page on GitHub

Install GitOps Runtime alongside Community Argo CD

Install GitOps Runtime on cluster with existing Argo CD

GitOps Runtime alongside Community Argo CD

If you have a cluster with a version of Community Argo CD already installed, you can install the GitOps Runtime to co-exist with your existing Argo CD installation. This option enables you to extend your environment with Codefresh’s GitOps capabilities through a few simple configuration changes, without the need to uninstall Argo CD.

Enhance CI/CD with Codefresh GitOps
Dive into the world of Codefresh GitOps, exploring its capabilities and features without having to uninstall or reconfigure existing Argo CD installations. Read about our GitOps offering in Codefresh for GitOps.
Gradual migration to GitOps applications
After becoming familiar with Codefresh GitOps, make informed decisions when migrating your Argo CD Applications to Codefresh GitOps.

For a smooth transition from Argo CD Applications to the same managed by Codefresh, migrate them at your preferred pace. After successful migration, view, track, and manage all aspects of the applications in Codefresh.

What you need to be aware of

Installing alongside Community Argo CD requires additional flags in the installation command for all access modes: tunnel, ingress, and service-mesh:

fullnameOverride configuration for resource conflicts
Conflicts can occur when resources in both Community and Codefresh’s Argo CD instances have the same name or attempt to control the same objects. Customizing fullnameOverride values for Argo CD (and Argo Rollouts if installed) in the GitOps Runtime’s values file prevents these conflicts.
Resource tracking with annotation
Installing the GitOps Runtime on the same cluster as Argo CD requires that each Argo CD instance uses a different method to track resources. Using the same tracking method can result in conflicts when both instances have applications with the same names or when tracking the same resource. Setting the GitOps Runtime’s Argo CD resource tracking to annotation+label prevents such conflicts.

`values.yaml` validation

The Codefresh values.yaml located here, contains all the arguments you can configure, including optional ones.

Before initiating the installation, Codefresh automatically validates the values.yaml file to verify that the supplied values are correct. A validation error will automatically terminate the installation.

You can disable automated validation globally for all installation settings, or for only the ingress controller for example, and run validation manually.

Validated settings

The table below lists the settings validated in the values file.

Setting	Validation
userToken	If explicitly defined, or defined as a `secretKeyRef` which exists in the current k8s context and the defined namespace.
Account permissions	If the user has admin permissions for the account in which they are installing the runtime.
Runtime name	If defined, and is unique to the account.
Access mode	For tunnel-based (the default), if `accountId` is defined, and matches the account of the `userToken` defined in the file. For ingress-based, if the hosts array contains at least one entry that is a valid URL (successful HTTP GET). If both tunnel-based and ingress-based access modes are disabled, if `runtime.ingressUrl` is defined.
gitCredentials	When defined, if includes a Git password either explicitly, or as a `secretKeyRef`, similar to `userToken`. The password or token has the required permissions in the Git provider.

Validation failures

If there is a validation failure, Codefresh terminates the installation with the error message:
Job has reached the specified backoff limit

To get more detailed and meaningful information on the reason for the validation failure, run:
kubectl logs jobs/validate-values -n ${NAMESPACE}
where:

{NAMESPACE} must be replaced with the namespace of the Hybrid GitOps Runtime.

Disable global installation validation

You may want to disable automated validation for specific scenarios, such as to address false-negatives.

To do so, either add the --set installer.skipValidation=true flag to the Helm install command, or the installer.skipValidation: true the values file.

In install command

--set installer.skipValidation=true

In values file

 
...
installer: skipValidation: true
...

Disable ingress validation

Ingress validation checks if the ingress URL exists and responds to web requests. During a GitOps Runtime installation, the ingress might not be active yet, causing DNS errors despite correct configuration. Disabling ingress validation allows the installation to proceed, assuming the ingress will work once the Runtime is fully operational.

Similar to disabling installation validation globally, you disable the validation for ingress by either adding the flag to the Helm install command, or by adding the line to the relevant section in the values file.

In install command

--set global.runtime.ingress.skipValidation=true

In values file

 
...
global:
  runtime:
    ingress:
      skipValidation: true
...

Manually validate values.yaml

To manually validate the values file, run:
cf helm validate --values <values_file> --namespace <namespace> --version <version>
where:

<values_file> is the name of the values.yaml used by the Helm installation.
<namespace> is the namespace in which to install the Hybrid GitOps runtime, either the default codefresh, or the custom name you intend to use for the installation. The Namespace must conform to the naming conventions for Kubernetes objects.
<version> is the version of the runtime to install.

Before you begin

Make sure you meet the minimum requirements for installation
Verify that you complete all the prerequisites:
- Switch ownership of Argo Project CRDs
- Prerequisites: Cluster with Community Argo CD
Git provider requirements:
- Git Runtime token with the required scopes which you need to supply as part of the Helm install command
- Git user token with the required scopes to authorize Git-based actions per user
- Server URLs for on-premises Git providers
For ingress-based and service-mesh based Runtimes only, verify that these ingress controllers are configured correctly:

Install Hybrid GitOps Runtime via Helm with Community Argo CD

Step 1: Select Hybrid Runtime install option

On the Getting Started page, click Install Runtime.
Continue with Step 2: Set up GitOps Git provider.

Step 2: Set up GitOps Git provider

As a one-time action, define the Shared Configuration Repository and the Git provider to associate with your account.

The Git provider you select for the first GitOps Runtime in your account is used for all the other Runtimes installed in the same account.

Shared Configuration Repository

The Shared Configuration Repository is a Git repository with configuration manifests shared between all the Hybrid GitOps Runtimes within the same account. Codefresh identifies the Git provider from the URL of the Shared Configuration Repo, and for cloud providers, automatically populates the Git Provider and the API URL fields.

You can specify only the repository URL, or add the path, reference a branch, or both:

<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. The .git suffix is recommended. 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

Git providers

On-premises Git providers require you to define the API URL:

GitHub Enterprise: https://<server-url>/api/v3
GitLab Server: <server-url>/api/v4
Bitbucket Data Center: <server-url>

How to

Define the URL of the Shared Configuration Repository.
If required, select the Git provider from the list.
If required, define the API URL for the Git provider you selected.

Define Shared Configuration Repo and Git provider

Click Next.
Continue with Step 3: Install Hybrid Runtime.

Step 3: Install Hybrid GitOps Runtime

Install the Hybrid GitOps Runtime through the Helm chart. The Codefresh values.yaml is located here.

TIP
Before initiating the installation, Codefresh automatically validates the values.yaml file to verify that the supplied values are correct.
If the Helm installation is terminated with the error message: Job has reached the specified backoff limit, get more detailed information on the reason for the validation failure with:
kubectl logs jobs/validate-values -n ${NAMESPACE}, replacing {NAMESPACE} with the namespace of the Hybrid GitOps Runtime.

Runtime Name
If you define a custom name for the Hybrid GitOps Runtime, it must start with a lower-case character, and can include up to 38 lower-case characters and numbers.

Namespace
The Namespace must conform to the naming conventions for Kubernetes objects.

Access modes
You can define one of three different access modes:

Tunnel-based, the default mode, is automatically enabled when the other access modes are not defined in the installation command.
Ingress-based, uses an ingress controller, which, depending on the type of ingress controller, may need to be configured both before and after installation. See Ingress controller configuration.
Service-mesh-based, which requires explicitly disabling the tunnel- and ingress-based modes in the installation command. The service mesh may also need to be configured before and after installation. See Ingress controller configuration in this article.

How to

To generate your Codefresh API key, click Generate.

If needed, select Customize runtime values, and define the Runtime Name and Namespace. The default names are codefresh for both.
Copy and run the command to install the runtime Helm chart:
The commands differ depending on the access mode. Ingress-based or service-mesh-based access modes for the Runtime require additional flags.
Unless otherwise indicated, values are automatically populated by Codefresh. If you’re using a terminal, remember to copy the values from the UI beforehand.

Tunnel-based install chart command:

helm upgrade --install <helm-release-name> \
  --create-namespace \
  --namespace <namespace> \
  --set global.codefresh.accountId=<codefresh-account-id> \
  --set global.codefresh.userToken.token=<codefresh-api-key> \
  --set global.runtime.name=<runtime-name> \
  --set argo-cd.fullnameOverride=codefresh-argo-cd \
  --set argo-rollouts.fullnameOverride=codefresh-argo-cd \
  --set argo-cd.configs.cm.application.resourceTrackingMethod=annotation+label \  
  oci://quay.io/codefresh/gitops-runtime \
  --wait

Ingress-based install chart command:

helm upgrade --install <helm-release-name> \
  --create-namespace \
  --namespace <namespace> \
  --set global.codefresh.userToken.token=<codefresh-api-key> \
  --set global.runtime.name=<runtime-name> \
  --set global.runtime.ingress.enabled=true \
  --set "global.runtime.ingress.hosts[0]"=<ingress-host> \
  --set global.runtime.ingress.className=<ingress-class> \
  --set argo-cd.fullnameOverride=codefresh-argo-cd \
  --set argo-rollouts.fullnameOverride=codefresh-argo-cd \
  --set argo-cd.configs.cm.application.resourceTrackingMethod=annotation+label \  
  oci://quay.io/codefresh/gitops-runtime \
  --wait

Service-mesh-based install command (without ingress and tunnel):

helm upgrade --install <helm-release-name> \
  --create-namespace \
  --namespace <namespace> \
  --set global.codefresh.userToken.token=<codefresh-api-key> \
  --set global.runtime.name=<runtime-name> \
  --set global.runtime.ingressUrl=<ingress-url> \
  --set global.runtime.ingress.enabled=false \
  --set tunnel-client.enabled=false \
  --set argo-cd.fullnameOverride=codefresh-argo-cd \
  --set argo-rollouts.fullnameOverride=codefresh-argo-cd \
  --set argo-cd.configs.cm.application.resourceTrackingMethod=annotation+label \  
  oci://quay.io/codefresh/gitops-runtime \
  --wait

where:

- <helm-release-name> is the name of the Helm release, and is either cf-gitops-runtime which is the default, or the release name you define.
- <namespace> is the namespace in which to install the Hybrid GitOps runtime, and is either codefresh which is the default, or the custom name you define.
- <codefresh-account-id> is mandatory only for tunnel-based Hybrid GitOps Runtimes , which is also the default access mode. Automatically populated by Codefresh in the installation command.
- <codefresh-api-key> is the API key, either an existing one or a new API key you generated. When generated, it is automatically populated in the command.
- <runtime-name> is the name of the GitOps Runtime, and is either codefresh which is the default, or the custom name you define.
- gitops-runtime is the chart name defined by Codefresh, and cannot be changed.
- Ingress-based Runtimes:
  - global.runtime.ingress.enabled=true is mandatory for ingress-based Hybrid GitOps Runtimes, and indicates that the runtime is ingress-based.
  - <ingress-host> is mandatory for ingress-based Hybrid GitOps Runtimes, and is the IP address or host name of the ingress controller component.
  - <ingress-class> is mandatory for ingress-based Hybrid GitOps Runtimes, and is the ingress class of the ingress controller. For example, nginx for the NGINX ingress controller.
- Service-mesh-based Runtimes:
  - global.runtime.ingressUrl=<ingress-url> is the ingress URL that is the entry point to the cluster.
  - global.runtime.ingress.enabled=false disables the ingress-based access mode.
  - tunnel-client.enabled=false disables the tunnel-based access mode.
- argo-cd.fullnameOverride=codefresh-argo-cd is mandatory to avoid conflicts at the cluster-level for resources in both the Community Argo CD and GitOps Runtime’s Argo CD.
- argo-rollouts.fullnameOverride=codefresh-argo-rollouts is mandatory when you have Argo Rollouts in your cluster to avoid conflicts.
- argo-cd.configs.cm.application.resourceTrackingMethod=annotation+label is mandatory to avoid conflicts when tracking resources with the same application names or when tracking the same resource in both the Community Argo CD and GitOps Runtime’s Argo CD.
- --wait is optional, and when defined, waits until all the pods are up and running for the deployment.

Wait for a few minutes, and then click Close. You are taken to the List View for GitOps Runtimes where:
- The Hybrid GitOps Runtime you added is prefixed with a green dot indicating that it is online.
- The Type column for the Runtime displays Helm.
- The Sync Status column displays Complete Installation, indicating that there are pending steps to complete the installation.
- Drilling down into the Runtime shows empty tabs for Runtime Components, Git Sources, and Managed Clusters.
  The Runtime Components are populated only when the GitOps Runtime is configured as an Argo Application, described later on in the installation process.

Newly installed Hybrid GitOps Runtime with Complete Installation notification

Continue with Step 4: Configure Git credentials for runtime.

Step 4: Configure Git credentials for Hybrid GitOps Runtime

Configure Git credentials to authorize access to and ensure proper functioning of the GitOps Runtime.
This is the first of the three steps needed to complete installing Hybrid GitOps Runtimes, the others being to add a Git user token and configure the Runtime as an Argo Application, described in the steps that follow this one.

Git credentials include authorizing access to Git repositories through OAuth2 or a Git Runtime token, and optionally configuring SSH access to the Git installation repo for the Runtime.

Git OAuth2 authorization
OAuth2 authorization is possible if your admin has registered an OAuth Application for Codefresh. See OAuth2 setup for GitOps.

Git access token authorization
Git access token authentication requires you to generate an access token in your Git provider account for the GitOps Runtime with the required scopes. For detailed information on Git Runtime token, including using tokens with custom scopes, review GitOps Runtime token scopes.

SSH access to Git
By default, Git repositories use the HTTPS protocol. You can also use SSH to connect Git repositories by entering the SSH private key. When SSH is configured for a GitOps Runtime, on creating/editing Git-Source applications, you can select HTTPS OR SSH as the protocol to connect to the Git repository. See Repository URL in Application Source definitions.

For more information on generating SSH private keys, see the official documentation:

Before you begin

To authenticate through a Git Runtime access token, make sure your token is valid and has the required scopes and is set up as required
To use SSH, copy the SSH private key for your Git provider

How to

In the Sync Status column for the Runtime you just installed, click Complete Installation. Codefresh displays the steps needed to complete the installation.

Steps to complete installing Hybrid GitOps Runtime

Do one of the following:
- If your admin has set up OAuth access, click Authorize Access to Git Provider. Go to step 3.
- Alternatively, authenticate with an access token from your Git provider. Go to step 4.

For OAuth2 authorization:

NOTE
If the application is not registered and you get an error, contact your admin for help.
- Enter your credentials, and select Sign In.
- If required, as for example with two-factor authentication, complete the verification.

For Git token authentication, in the Git Runtime Token field, paste the Git Runtime token you generated.
Optional. To configure SSH access to Git, expand Connect Repo using SSH, and then paste the raw SSH private key into the field.
Click Update Credentials. Codefresh displays a message that the Git Runtime credentials have been updated.
Continue with Step 5: Add Git user token.

Step 5: Add Git user token

Add a Git user token, as a personal access token unique to each user. The permissions for the Git user token are different from those of the Git Runtime token. Verify that you have an access token from your Git provider with the correct scopes.

This is the second of three steps needed to complete installing Hybrid GitOps Runtimes, the others being to add a Git Runtime token (previous step) and configure the Runtime as an Argo Application (following step).

TIP
If you already have added a Git user token, you can skip this step.

Click Git user token to add your personal access token to authorize actions to Git repositories.
Continue with Step 6: (Optional) Configure Hybrid GitOps Runtime as Argo Application.

Step 6: (Optional) Configure Hybrid GitOps Runtime as Argo Application

Configure the Hybrid GitOps Runtime as an Argo Application as the final step in the installation process. By doing so, you can view the Runtime components, monitor health and sync statuses, and ensure that GitOps is the single source of truth for the Runtime.

NOTE
You cannot configure the Runtime as an Argo Application if you have not configured Git credentials for the Runtime, as described in the previous step.

Go back to the List view.
Click Configure as Argo Application. Codefresh takes care of the configuration for you. If you drill down into the Runtime and click Runtime Components, you’ll see the list of components with their Health status.

Runtime Components after configuring GitOps Runtime as Argo Application

Continue with Step 7: (Optional) Create a Git Source.

Step 7: (Optional) Create a Git Source

Create a Git Source for the Runtime. A Git Source is a Git repository managed by Codefresh as an Argo CD application.
You can always create Git Sources after installation whenever you need to in the Codefresh UI.

Optional. Create a Git Source.
Continue with Step 8: (Optional) Configure ingress-controllers.

Step 8: (Optional) Configure ingress-controllers

Required only for ALB AWS and NGINX Enterprise ingress-controllers, and Istio service meshes.

Complete configuring these ingress controllers:

After successful installation, you may need to complete additional steps based on your Argo CD setup: if you have Argo Rollouts, remove the Rollouts controller deployment.
Based on your requirements, migrate Community Argo CD Applications to the GitOps Runtime to manage them in Codefresh.

Remove Rollouts controller deployment

If you have Argo Rollouts also installed with Community Argo CD, after confirming successful installation, remove the duplicate Argo Rollouts controller deployment to avoid having two controllers in the cluster.

IMPORTANT
Make sure to remove only deployment and not the CRDs. Removing the CRDs also removes Rollout objects resulting in downtime for workloads.

Remove the duplicate Argo Rollouts controller:
kubectl delete deployment <argo-rollouts-controller-name> -n <argo-rollouts-controller-namespace>

Migrate Community Argo CD Applications to Codefresh GitOps Runtime

The final task, depending on your requirements, is to migrate your Community Argo CD Applications to the Codefresh GitOps Runtime.

Why would you want to do this?
Because this allows you to completely and seamlessly manage the applications in Codefresh as GitOps entities.

The process to migrate an Argo CD Application is simple:

Add a Git Source to the GitOps Runtime to which to store application manifests
Make the needed configuration changes in the Argo CD Application
Commit the application to the Git Source for viewing and management in Codefresh

Step 1: (Optional) Add a Git Source to GitOps Runtime

If you have already added a Git Source as part of the Hybrid GitOps Runtime installation procedure, skip this step.

Otherwise, add a Git Source to the GitOps Runtime to which you can commit your applications. A Git Source is a Git repository managed by Codefresh as an Argo CD Application. Read about Git Sources.

Add a Git Source to your GitOps Runtime.

Step 2: Modify Argo CD applications

Modify the Argo CD Application’s manifest to remove finalizers if any, and also remove the Application from the argocd namespace it is assigned to by default.

Remove metadata.namespace: argocd.
Remove metadata.finalizers.

Below is an example of a manifest for an Argo CD Application with finalizers.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-sample-app
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    path: guestbooks/apps
    repoURL: https://github.com/codefresh-codefresh/argocd-example-apps
    targetRevision: personal-eks
  destination:
    namespace: my-app
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      prune: false
      selfHeal: false
      allowEmpty: false
    syncOptions:
      - PrunePropagationPolicy=foreground
      - Replace=false
      - PruneLast=false
      - Validate=true
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=false
      - ServerSideApply=false
      - RespectIgnoreDifferences=false

Step 3: Commit Argo CD application to Git Source

As the final step in migrating your Argo CD Application to a GitOps Runtime, manually commit the updated application manifest to the Git Source you created. Once you commit the manifest to the Git Source, it is synced with the Git repo. You can view it in the Codefresh UI, modify definitions, track it through our different dashboards, and in short, manage it as you would any GitOps-controlled resource in Codefresh.

Go to the Git repo where you created the Git Source.
Add and commit the Argo CD Application manifest to the Git Source. Here’s an example of the my-sample-app above committed to a Git Source without metadata.namespace: argocd and metadata.finalizers.

Argo CD Application committed to GitOps Git Source

In the Codefresh UI, from the sidebar, below Ops, select GitOps Apps. The Applications Dashboard displays the new Git Source application.

GitOps Apps dashboard with Git Source and migrated Application

Click the application to drill down to the different tabs. The Configuration tab displays the application’s settings which you can modify and update. Here’s an example of the Current State tab for my-sample-app.

Current State tab for migrated Argo CD application

Monitoring GitOps Runtimes
Managing GitOps Runtimes Managing Git Sources in GitOps Runtimes
Managing external clusters in GitOps Runtimes

Install GitOps Runtime alongside Community Argo CD

GitOps Runtime alongside Community Argo CD

What you need to be aware of

values.yaml validation

Validated settings

Validation failures

Disable global installation validation

In install command

In values file

Disable ingress validation

In install command

In values file

Manually validate values.yaml

Before you begin

Install Hybrid GitOps Runtime via Helm with Community Argo CD

Step 1: Select Hybrid Runtime install option

Step 2: Set up GitOps Git provider

Shared Configuration Repository

Git providers

How to

Step 3: Install Hybrid GitOps Runtime

How to

Step 4: Configure Git credentials for Hybrid GitOps Runtime

Before you begin

How to

Step 5: Add Git user token

Step 6: (Optional) Configure Hybrid GitOps Runtime as Argo Application

Step 7: (Optional) Create a Git Source

Step 8: (Optional) Configure ingress-controllers

Remove Rollouts controller deployment

Migrate Community Argo CD Applications to Codefresh GitOps Runtime

Step 1: (Optional) Add a Git Source to GitOps Runtime

Step 2: Modify Argo CD applications

Step 3: Commit Argo CD application to Git Source

Related articles

`values.yaml` validation