Improve this page on GitHub

On-premises GitOps Runtime installation

Install GitOps Runtime in on-premises environments using Helm

Install the GitOps Runtime in your on-premises environments with Helm to create and manage Argo CD applications and deployments.

IMPORTANT
Tunnel-based access mode is not supported for GitOps on-premises installations.

Install GitOps Runtime on-premises

Run:

helm upgrade --install cf-gitops-runtime \
  --create-namespace \
  --namespace codefresh \
  --set global.codefresh.userToken.token=<codefresh-token> \
  --set global.runtime.name=codefresh \
  --set global.codefresh.url=<on-prem-url> \
  --set app-proxy.config.cors=<on-prem-url> \
  --set global.runtime.ingress.enabled="true" \
  --set "global.runtime.ingress.hosts[0]"=<ingress-host> \
  cf-gitops-runtime/gitops-runtime

where:

<namespace> (required) is the namespace in which to install the Hybrid GitOps Runtime on-premises, either codefresh, or any custom name.
<codefresh-token> (required) is the API token you have generated in Codefresh. You can use existing token, or generate a new API token.
<runtime-name> (required) is the name of the runtime, either codefresh, or any custom name.
<on-prem-url>(required) is the URL of your platform, for example, https://codefresh-onprem.com.
<ingress-host> (required) is the hostname used to access the runtime without https://. Make sure the "global.runtime.ingress.hosts[0]" is within double quotes.
global.runtime.ingress.enabled="true" (required) value must be within double quotes.

Values file for on-prem GitOps Runtime

Here’s an example of the values.yaml for installing the GitOps Runtime on-premises.

global:
  codefresh:
    url: https://codefresh-onprem.com  ## required, replace with your platform URL
    

    userToken:
      token: 16363747847837838757885898 ## required, use an existing Codefresh API token or generate a new one

  runtime:
    name: noamg-runtime

    ingress:                                   # on-prem supports only ingress-based
      enabled: true
      hosts:
      - codefresh.ingress-host.com   ## required, replace with host used to access the runtime without `https://`

app-proxy:
  config:
    cors: https://codefresh-onprem.com  ## required, must be identical to platform URL

Mirroring Helm chart in on-premises/air-gapped environments

After installing the GitOps On-premises Runtime in on-premises or air-gapped environments, you can manage it as an Argo Application to establish GitOps as the single source of truth for the Runtime. You can monitor the health and synchronization statuses of your Runtime components.

To manage the on-premises GitOps Runtime as an Argo Application, you need to:

Mirror the Helm chart to a repository that can be accessed by app-proxy
Set an environment variable in the values file in .values.app-proxy to reference the mirrored Helm repository, as shown in the example below.

...
app-proxy:
  env:
    HELM_REPOSITORY: https://codefresh-airgapped-helm-repo.s3.amazonaws.com/gitops-runtime
...

Image overrides for private registries

If you use private registries, you need to override specific image values for the different subcharts and container images.

We have a utility to help override image values for GitOps Runtimes. The utility creates values files that match the structure of the subcharts, allowing you to easily replace image registries. During chart installation, you can provide these values files to override the images, as needed. For more details, see ArtifactHub.

Argo project CRDs

If you already have Argo project CRDs on your cluster, do one of the following:

Handle Argo projects CRDs outside of the chart (see Argo’s readme on Helm charts)
Disable CRD installation under the relevant section for each of the Argo projects in the Helm chart:
--set <argo-project>.crds.install=false
where:
<argo-project> is the argo project component: argo-cd, argo-workflows, argo-rollouts and argo-events.
Adopt the CRDs
Adopting the CRDs allows them to be managed by the gitops-runtime helm release. Doing so ensures that a runtime upgrade also automatically upgrades the CRDs.

Run this script before installation:

#!/bin/sh
RELEASE=<helm-release-name>
NAMESPACE=<target-namespace>
kubectl label --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) app.kubernetes.io/managed-by=Helm
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-name=$RELEASE
kubectl annotate --overwrite crds $(kubectl get crd | grep argoproj.io | awk '{print $1}' | xargs) meta.helm.sh/release-namespace=$NAMESPACE

Custom certificates for on-premises installations

For on-premises installations, you may need to configure custom platform and repository certificates:

Platform certificates are required for GitOps Runtimes to communicate with the Codefresh platform.
Repository certificates are required to authenticate users to on-premises Git servers.

Platform certificates

Get your certificate:

HOST=codefresh-onprem.com # put in the hostname of your on-prem platform, without a schema
openssl s_client \
  -showcerts \
  -connect ${HOST}:443 \
  -servername ${HOST} \
  </dev/null 2>/dev/null \
  | awk '/^-----BEGIN CERTIFICATE-----$/,/^-----END CERTIFICATE-----$/ { print }'

Include them in .values.global. You can either reference an existing secret or create a new secret directly within the file.
All certificates must be below content: |.

global:
  codefresh:
    tls:
      caCerts:
        # optional - use an existing secret that contains the cert
        # secretKeyRef:
        #   name: my-certificate-secret
        #   key: ca-bundle.crt
        # or create "codefresh-tls-certs" secret
        secret:
          create: true
          content: |
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----

Repository certificates

Add repository certificates to your Codefresh values file, in .values.argo-cd. These values are used by the argo-cd Codefresh deploys. For details on adding repository certificates, see this section.

argo-cd:
  configs:
    tls:
      certificates:
        server.example.com: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

Ingress controller configuration

Ingress-based on-premises GitOps Runtimes require an ingress controller to be configured before the installation. For details, see Ingress controller configuration. Depending on the ingress controller used, you may need post-installation configuration as well.

Managing and monitoring GitOps Runtimes
On-premises platform architecture