Bring Your Own Argo CD into Harness GitOps
Learn how to import your existing Argo CD configuration into Harness GitOps using a Bring Your Own Argo CD (BYOA) setup.
This topic describes how to import your existing Argo CD configuration into Harness GitOps as a Bring Your Own Argo CD (BYOA) setup.
In addition, when you install the Harness GitOps Agent in your existing Argo CD cluster as part of BYOA, you can map Argo CD projects to Harness projects. Harness imports all the Argo CD project entities (for example, applications, clusters, and repos) and creates them in Harness automatically.
Also, whenever new entities are created in the mapped Argo CD projects, they are added to Harness automatically.
With a standard Harness GitOps Agent installation (non-BYOA), Harness can install and manage Argo CD for you. This scenario is different from a BYOA where you are importing an existing Argo CD configuration into Harness GitOps.
Go to Install a Harness GitOps Agent to install a GitOps Agent.
What you will learn from this topic
How to install a GitOps Agent in an existing Argo CD setup (BYOA)
How to map existing Argo CD projects to Harness projects
How to view saved import history for a GitOps Agent
How to verify the mapping and confirm imported entities
How to add new mappings to an existing agent
How to enable Harness expression resolution for BYOA setups
Argo CD project mapping across Harness scopes
To map Argo CD projects to Harness projects, you need to install the Harness GitOps Agent from the Harness account or organization level. Then you can map the Argo CD projects to any of the Harness projects in the account or organizations.
If you install the GitOps Agent at the Harness project level, you can only map to the current project.
The following example installs the GitOps Agent at the Harness account level.
Install a GitOps Agent in an existing Argo CD setup (BYOA)
The following steps show you how to install a GitOps Agent into an existing Argo CD namespace and then map your existing projects to your Harness project.
In your Harness account, select Account Settings.
Select GitOps, and then select Agents.

GitOps Agents page in Account Settings Select New GitOps Agent.
In Agent Installation, in Do you have any existing Argo CD instances, select Yes, and then select Start.

Agent Installation screen asking about existing Argo CD instances In Name, enter a name for your agent, such as
byoa-agent.In GitOps Operator, select Argo. Argo CD is the only supported GitOps reconciler. Flux is not supported.
In Namespace, enter the namespace where Argo CD is hosted. The default is
argocd.
Namespace field for the existing Argo CD installation Select Continue.
In Review YAML, select Download & Continue.
Log in to the cluster hosting Argo CD.
Run the install command provided in the Agent installer, such as
kubectl apply -f gitops-agent.yml -n argocd. You will see output similar to this:In the Harness GitOps Agent installer, select Continue.
The Agent has registered with Harness.

Select Continue. The Map Projects settings appear.
Map existing Argo projects
To map your existing Argo CD projects to Harness projects, select the Argo CD projects you want to use, and then select the Harness project where you want to map the Argo CD project.
In Map Projects, in Select your Argo Projects to Import, select the Argo CD projects you want to map.

Select Argo Projects to Import screen In each row, select the Argo project and the Harness project.

Map Projects screen pairing Argo CD and Harness projects To automatically create Harness services and environments during the import, enable the Enables automatic creation of service environments toggle on the Map Projects screen.

Enables automatic creation of service environments toggle on the Map Projects screen When this toggle is enabled, Harness checks each Argo CD application for
harness.io/serviceRefandharness.io/envReflabels. If a service or environment matching the label value already exists in the target Harness project, the application is mapped to it. If it does not exist, Harness creates the service or environment automatically and then maps it to the application.To use this feature, add the
harness.io/serviceRefandharness.io/envReflabels to themetadata.labelssection of your Argo CD Application YAML before importing.Select Import & Continue.
The Argo CD projects are imported. When auto-creation is enabled, the import summary also shows the number of services, environments, and cluster links created or mapped.

Import summary showing created services, environments, and cluster links Select Finish. The mapping is displayed in the Agent details.

Argo CD project mapping shown in the Agent details Select Save.
View import history
To review past Argo CD project imports for an Agent, go to Account Settings -> GitOps Agents, open the Agent, and select the History Audit tab. The tab keeps a record of each import, including the services, environments, and linked clusters that Harness created, so you can review the outcome after the import finishes.
The History Audit tab lists the imports for the Agent in a table with the columns Action, Import Request ID, Services, Environments, Linked Clusters, Performed By, Time, and Actions. By default, the tab shows imports from the last 7 days. Use the date filter to change the time range, or enter an import request ID in the search box to find a specific import.
To see the outcome for each resource in an import, select the row to expand it. The expanded row lists one line per resource with the columns Status, Type, Resource, Application, Details, and Time. Status shows whether the resource was created or linked, or whether Harness raised a warning. Details explains the result, for example that a cluster is already linked to the environment. Select an entry in Application to go to that application.

Harness also records an audit event when an import starts and when it ends. To view the audit for an import, select the icon in the Actions column. The Import Event Summary panel opens with the action, import request ID, and the user who performed it. The YAML Difference view lists the audit data for that import, such as applicationCount, clusterCount, and the counts of services, environments, and cluster links that were created or failed.

Verify mapping
To view the imported Argo CD entities from the mapping, look in the mapped Harness project.
In your Harness project, select GitOps, and then select Applications. You can see the imported applications.

Imported GitOps applications in Harness Select Settings, and then select Repositories. You can see the imported repositories.
Select Settings, and then select Clusters. You can see the imported clusters.
Do the same for any other mapped project entities.
Verify auto-created services and environments
If you enabled the Enables automatic creation of service environments toggle during the import, verify that the services and environments were created correctly.
In your Harness project, select Services in the left navigation. You can see the services that Harness created automatically based on the
harness.io/serviceReflabels in your application manifests.
Automatically created services in Harness Select Environments in the left navigation. You can see the environments that Harness created based on the
harness.io/envReflabels.
Automatically created environments in Harness To confirm that an application is mapped to the correct service and environment, go to GitOps > Applications, select an application, and open the App Details tab. The Service and Environment fields display the mapped values.

App Details tab showing the mapped service and environment
Add new mappings to an existing agent
You can add new mappings to an existing Agent in the Agent's Mapped Harness Project settings.
In Harness, open an existing Agent.
Select Edit. In this example, the Argo CD project alpha is mapped to the Harness project GitOps.

Editing an existing Agent's project mapping
Add a new mapping.
In Mapped Harness Project, select Add.
In Map Projects, in Select your Argo Projects to Import, select an Argo CD project. Do not select a project you have already mapped.
Map the Argo CD project to a Harness project, then select Import & Continue. Do not re-map an existing mapping. Harness returns an error.

Mapping an additional Argo CD project to a Harness project When the import is complete, select Finish.
Both projects are mapped.

Automatic addition of Argo CD entities to Harness
When an Agent contains Argo CD project mappings to a Harness project, any new entities added to the Argo CD project are added to the mapped Harness project automatically.
Try adding a new Argo CD repository to the mapped Argo CD project.
After it is saved in Argo CD, go to Harness and look at the GitOps repositories in the mapped Harness project. A new repository is added.
Automatically added Argo CD repositories
When Argo CD repositories are added to Harness, Harness automatically generates a name for each repository. Name generation is necessary because Argo CD has no name setting for its repositories. When generating a name for a repository, Harness removes any dashes from the name of the repository, and then appends an underscore followed by a unique suffix.
For example, the Argo CD repository https://github.com/argoproj/gitops-engine.git is named gitopsengine_kmjzyrbs in Harness.

Ensure your Argo CD entities are visible in Harness
In some Argo CD versions, you are not required to specify a project for your entities. However, for the entities to be visible in Harness, you must associate the entities with a project.
If you are unable to edit an entity from the Argo CD UI, you can edit that entity in the cluster so that they have a project and other required values. The entities are stored in different formats in the cluster. For example, clusters, repositories, and repository credential templates are stored in Secret, and GnuPG keys and repository certificates are stored in ConfigMap in the namespace where Argo CD is installed.
Edit the respective secret of the entity and add the fields project and name in the data or stringData block. Go to Manage an Argo CD configuration in Git with Harness GitOps for examples.
Create GitOps entities with multiple projects
When you have multiple Argo CD projects mapped to your Harness project, you can choose which Argo CD project to use when you create a new GitOps entity (cluster, repository, or application) in your Harness project.
By default, in the Argo CD console, when you create a cluster, it is not associated with an Argo CD project. You can add the cluster by using the argocd cluster add CLI and its --project option.
The following steps are common to all three entities (clusters, repositories, and applications) when you create them in Harness. The example below uses a GitOps cluster:
While creating a GitOps cluster in the Harness project that is mapped to multiple Argo CD projects, under GitOps Agent, select the Agent where you set up the mappings. The Project setting appears.
If the Agent has only one Argo CD project mapped, the Project setting is not shown.
In Project, select the Argo CD project with the cluster you want to import.

Selecting the Argo CD project for the cluster
When you have completed setting up the cluster, the cluster appears in the GitOps Cluster list.
Enable Harness expression resolution for existing installations
Prerequisites
The feature flag
CDS_GITOPS_SECRET_RESOLUTION_ENABLEDmust be enabled. Contact Harness Support to enable it.Minimum GitOps agent version: v0.105.x or later.
Plugin sidecar image version:
harness/gitops-agent-installer-helper:v0.3.0.
With a BYOA setup, you can enable the Harness ArgoCD plugin to use Harness secret expressions directly in your application manifests. This feature allows you to reference secrets stored in Harness (such as database passwords and API keys) within your Kubernetes manifests, and the expressions are resolved and decrypted during manifest rendering.
Go to Harness Secret Expressions in Application Manifests for feature requirements, supported secret managers, and usage examples.
For Helm chart installations
If your GitOps agent was installed using the Harness-provided Helm chart, follow these steps:
Upgrade to the latest chart and make the following changes to your
values.yamlfile.Enable the Harness ArgoCD plugin by adding the following flag:
Add the agent service configuration under the
agentsection:Add the plugin container to the Argo CD repo server by adding the following under
argo-cd.repoServer.extraContainers:Add the ConfigMap volume to the repo server by adding the following under
argo-cd.repoServer.volumes:Apply the changes by running the Helm upgrade command:
For plain Kubernetes manifest installations
If your GitOps agent was installed using plain Kubernetes manifests, follow these steps:
Create the agent service (if it does not already exist):
Apply this manifest:
Create the plugin ConfigMap in the same namespace as your GitOps agent/Argo CD:
Apply this ConfigMap:
Add the plugin sidecar container to the
argocd-repo-serverdeployment:Edit the
argocd-repo-serverdeployment and add the following container underspec.template.spec.containers:Apply the updated deployment:
Verify the installation by checking that the plugin container is running:
Verify the plugin installation
After completing the installation, verify that the Harness plugin is working correctly:
Check that the
argocd-repo-serverpods are running with the new sidecar containerVerify that the plugin ConfigMap exists in the namespace
Test expression resolution by deploying an application with Harness secret expressions
Go to Harness Secret Expressions in Application Manifests for usage examples and expression syntax.
Additional considerations
Consider the following:
Harness honors Argo CD project permissions. If the project selected for the Harness application does not have permissions for the repository or cluster, then Harness returns a permissions-related error. You must go to Argo CD and adjust the project's scoped repositories and destinations.
A non-BYOA setup does not support mapping multiple Argo CD projects to a single Harness project.
Argo CD version upgrades: If you upgrade your Argo CD version to any version that is >= v2.8.0 with a BYO Argo GitOps agent installed, you will have to restart the agent pods in order for the agent to pickup the required configuration change. You can restart the deployment or the pods individually.
Next steps
Install a Harness GitOps Agent: Review agent installation options.
Create and manage ApplicationSets: Use ApplicationSets with your BYOA setup.
Manage an Argo CD configuration in Git: Manage ArgoCD configurations declaratively.
Last updated
Was this helpful?