Argo CD Instances

An Argo CD instance is represented in Octopus as a separate Infrastructure component, distinct from Deployment Targets or Workers.

Each Argo CD instance in Octopus represents a connection to a running Argo CD instance and is used as the anchor in which Argo CD applications are retrieved.

To connect Octopus Deploy to an Argo CD instance, a network gateway must first be installed in your Kubernetes cluster, the Octopus Argo CD Gateway.,

The gateway creates a TLS-encrypted, outgoing gRPC connection from the host Kubernetes cluster to Octopus Server, and routes data from Argo CD to your Octopus Server instance. This gateway means that no publicly accessible HTTP/gRPC URL is required for communication, providing added security.

A gateway is required for each Argo CD Instance being connected to Octopus.

Installing the Octopus Argo CD Gateway

The gateway is installed using Helm via the octopusdeploy/octopus-argocd-gateway-chart chart.

To simplify this, there is an installation wizard in Octopus to generate the required values.

kubectl config view

Configuration

1. Navigate to Infrastructure ➜ Argo CD Instances, and click Add Argo CD Instance
2. This launches the Register Argo CD Instance dialog

1. Enter the unique name for the instance. This name is used to generate the Kubernetes namespace, as well as the Helm release name.
2. Select at least one environment the instance will be responsible for servicing.
3. If required, change the in-cluster URL of the Argo CD API Server service. In many cases the default value provided will work.
4. Optionally, add the URL used to access Argo CD’s web frontend. This will be used for linking from Octopus to Argo CD to aid with deployment investigations.
5. A valid Argo CD JWT authentication token is required. To generate this, you can use the Argo CD CLI.
6. Press “Next” to move to the next screen

Installation helm command

At the end of the wizard, Octopus generates a Helm command that you copy and paste into a terminal connected to the target cluster. After it’s executed, Helm installs all the required resources and starts the gateway.

# For self-signed certificates - Disables TLS certificate verification
gateway.argocd.insecure="true"

# For no certificates - Disables TLS entirely, all traffic between the Gateway and Argo traffic will be unencrypted
gateway.argocd.plaintext="true"

If left open, the installation dialog waits for the gateway to establish a connection and run a health check. Once successful, the Octopus Argo CD gateway is ready for use!

Health Checks and Updating

Octopus performs health checks on the gateway in a manner similar to that used for workers and deployment targets.

The gateway uses an internal cronjob to ensure it is always running the latest version.

Status Display

Your connected ‘Argo CD Instances’ appear under the Octopus’ Infrastructure menu. These pages allow you to:

• View and edit the Octopus-managed properties of your Argo CD Instance (eg permitted environments),
• View known Argo Applications, and how they map to Octopus project/environment/tenants
• View connectivity and health related data of the instance and gateway

Next steps

After the gateway has been configured, you need to define the relationships between Argo CD Applications and Octopus Projects, Environments and/or Tenants.

See Scoping Annotations for more information

Versioning

The Octopus Argo CD Gateway Helm chart follows Semantic Versioning. Generally, version updates can be interpreted as follows:

• major - Breaking changes to the chart. This may include adding or removing of resources, breaking changes in the Octopus Argo CD Gateway application image, breaking changes to the structure of the values.yaml. Upgrading to a major version might involve modifying your Gateway’s configuration or upgrading to a version of Octopus that supports the major version
• minor - New non-breaking features. New features or improvements to the Octopus Argo CD Gateway application or helm chart itself.
• patch - Minor non-breaking bug fixes or changes that do not introduce new features.

Troubleshooting

Argo CD TLS Errors

If your Gateway is unable to connect to your Argo CD instance due to TLS errors it is likely due to the certificate that Argo CD is serving traffic with.

Self Signed Certificate

If you are getting an error that looks like this:

tls: failed to verify certificate: x509: certificate signed by unknown authority

It is most likely due to Argo CD using a self-signed certificate, if it is intended that your certificate is self-signed you can disable certificate verification by doing the following:

Using Helm for existing installation:

helm upgrade --atomic \
--version "1.0.0" \
--namespace "{{GATEWAY_NAMESPACE}}" \
--reset-then-reuse-values \
--set gateway.argocd.insecure="true" \
--set gateway.argocd.plaintext="false" \
{{EXISTING_HELM_RELEASE_NAME}} \
oci://registry-1.docker.io/octopusdeploy/octopus-argocd-gateway-chart

No Certificate

If you are running your Argo CD instance without a certificate due to terminating SSL at a load balancer level the Gateway will likely fail to connect with the following error:

transport: authentication handshake failed: EOF

This is because the Gateway is configured by default to require encrypted traffic, if it is intended that you don’t have a certificate you can disable encryption between the Gateway and Argo CD by doing the following:

helm upgrade --atomic \
--version "1.0.0" \
--namespace "{{GATEWAY_NAMESPACE}}" \
--reset-then-reuse-values \
--set gateway.argocd.insecure="false" \
--set gateway.argocd.plaintext="true" \
{{EXISTING_HELM_RELEASE_NAME}} \
oci://registry-1.docker.io/octopusdeploy/octopus-argocd-gateway-chart

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Monday, September 15, 2025