Skip to main content

Installing the Platform using Argo CD (Recommended)

We support and recommend Argo CD for deploying and operating the platform.

The blueprints we use and test daily are maintained here: Cluster infrastructure template (GitLab)

If not already done, create a Git repository, follow the structure and content based on the referenced repo, and adapt it to your needs.

This installation approach can be used for production and development (in case prerequisites are fulfilled).

Prerequisites​

  • Argo CD deployed
  • Access to the OCI Helm registry and container registry with a valid token (see Introduction & Deployment Approach)
  • Connect the infrastructure Git repository to Argo CD

Connect the Infrastructure Git repository to Argo CD​

  • Connection Method: https
  • Type: Git
  • Name: Choose a descriptive name for the repo.
  • Project: default
  • Repository URL: The GitLab infrastructure repo URL (ensure it exists beforehand).
  • Username/Password: Enter your Git credentials

Leave the remaining fields blank and click Connect.

Confirm the connection status is Successful.

Connect the OCI Helm registry to Argo CD​

  • Connection Method: https
  • Type: Helm
  • Name: Choose a descriptive name for the repo.
  • Project: default
  • Repository URL: registry.gitlab.com/olive6224315/helm-charts/charts
  • Username/Password: Enter your credentials that you can request from the OLIVE team
  • Enable OCI checkbox

Leave the remaining fields blank and click Connect.

Confirm the connection status is Successful.

Repository layout​

Both ApplicationSets below are generators — they discover what to deploy by walking the infrastructure repository. Neither makes sense without the layout they walk, so this is the layout the examples on this page assume, not a layout OLIVE requires:

helm/
<env>/ # lab, develop, platform, prod …
<namespace>/ # oli-single, oli-runtime-multi, oli-multi, oli-hashicorp-vault …
values.yaml # the values for this deployment
app.yaml # olivePlatformVersion for this deployment
charts/ # only for the per-chart approach
<chart>/
Chart.yaml # a thin wrapper declaring one OLIVE chart as a dependency

The generators index into that path, so within these examples the depth is load-bearing: index .path.segments 2 is the namespace in both. If your repository is organised differently, that is fine — adjust the index expressions to match it.

These are recommendations, not requirements

Everything below — the ApplicationSets, the repository layout they walk, and the naming — is how we deploy and test OLIVE ourselves. It is shared because it works and saves you designing it from scratch.

OLIVE does not dictate that you use an ApplicationSet at all, nor how your infrastructure repository is structured. Plain Application resources, an app-of-apps, your own generator or your organisation's existing GitOps conventions are all equally fine.

What OLIVE actually requires is narrower, and it is worth separating from the examples:

  • the charts are deployed with the right values, including the shared blocks that several charts read;
  • the deployment tool honours the sync waves the charts already declare, because several of them depend on a Job having completed. The olive-platform umbrella chart carries that ordering, so deploying it as one Application satisfies this on its own;
  • the AppProject permits what they create — see the section at the end of this page.

Meet those three and the layout is yours. The examples are one way of meeting them.

How to lay out the Applications​

Deploy the OLIVE platform as one Application per deployment, using the olive-platform umbrella chart. That is the arrangement to use, and the rest of this page assumes it.

There is a second layout — one Application per chart — which has a narrower place:

One tile per deploymentOne tile per chart
DeploysThe olive-platform umbrella chartEach chart as its own Application
Tiles in the Argo CD UIOne per namespace — a development deployment is one tile; a multi-tenant installation is one for the shared pool plus one per tenantOne per chart, per namespace — dozens for the platform
Use it forThe OLIVE platform. Ordering is already solved inside the umbrella chartThe five infrastructure charts — vault-infra, keycloak-infra, service-mesh-setup, kyverno-infra, traefik-infra — which are separate components with separate lifecycles
Do not deploy the OLIVE platform chart by chart

The per-chart layout is how OLIVE's own developers work on the platform: it lets one service be synced, rolled back or inspected without a whole-platform sync between attempts. That is a development workflow, not a deployment method.

As a platform administrator, use the umbrella chart. Splitting the platform into per-chart Applications means taking over ordering that the umbrella chart already handles correctly, and getting it wrong produces a sync that hangs rather than an error.

Where the per-chart layout is the right shape is the infrastructure charts. Each of those is an independent component installed once per cluster, on its own schedule and usually by the cluster operator — so one Application each is the natural arrangement, and there is no umbrella chart over them. See Cluster Operator → Infrastructure Charts, which shows the thin wrapper chart pattern each one uses.

One tile per deployment (olive-platform)​

One working example of an ApplicationSet in the argocd namespace, pointing at the infrastructure Git repository. An app.yaml per deployment pins the OLIVE Platform version — it can also be set in the ApplicationSet itself. Adapt names, labels and paths to your own conventions.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: applicationset-platform-lab
namespace: argocd
spec:
goTemplate: true
generators:
- git:
repoURL: https://<your-git-host>/<your-group>/cluster-infrastructure.git
revision: master
files:
- path: helm/lab/*/app.yaml # change the path to the appropriate path in your git repository
template:
metadata:
labels:
env: lab
helm: platform
name: "{{ index .path.segments 2 }}-lab"
spec:
project: "default"
sources:
- chart: olive-platform
helm:
valueFiles:
- $values/helm/lab/{{ index .path.segments 2 }}/values.yaml
repoURL: registry.gitlab.com/olive6224315/helm-charts/charts
targetRevision: '{{ .olivePlatformVersion }}'
- ref: values
repoURL: https://<your-git-host>/<your-group>/cluster-infrastructure.git
targetRevision: master
destination:
server: https://kubernetes.default.svc
namespace: "{{ index .path.segments 2 }}"
ignoreDifferences:
- group: ""
kind: Secret
jsonPointers:
- /data/username
- /data/password
- group: "secrets.hashicorp.com"
kind: VaultStaticSecret
jsonPointers:
- /spec/data
- group: apps
kind: Deployment
jsonPointers:
- /spec/template/spec/containers/0/env
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true

This is a multi-source Application: the chart comes from the OCI registry, the values come from Git. The ref: values source is what makes $values/... resolvable in valueFiles.

destination.server is https://kubernetes.default.svc when Argo CD deploys into its own cluster. For a remote cluster, use that cluster's API URL as registered in Argo CD.

The app.yaml each tile is generated from holds just the version:

olivePlatformVersion: "x.x.x"

When selecting an OLIVE Platform version, always use the latest officially released version. Do not use versions intended for internal OLIVE development — those carry postfixes such as dev or stage.

One tile per chart — for the infrastructure charts​

This layout discovers one Application per chart from charts/* directories. Use it for the five infrastructure charts, not for the OLIVE platform.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: applicationset-infra-lab
namespace: argocd
spec:
goTemplate: true
generators:
- git:
repoURL: https://<your-git-host>/<your-group>/cluster-infrastructure.git
revision: master
directories:
- path: helm/lab/*/charts/* # change the path to the appropriate path in your git repository
template:
metadata:
labels:
env: lab
helm: single-charts
name: "{{ index .path.segments 2 }}-{{ .path.basename }}-lab"
annotations:
argocd.argoproj.io/compare-options: '{{ if eq .path.basename "kyverno-infra" }}ServerSideDiff=true{{ end }}'
spec:
project: "default"
source:
repoURL: https://<your-git-host>/<your-group>/cluster-infrastructure.git
targetRevision: master
path: "{{ .path.path }}"
helm:
valueFiles:
- ../../values.yaml
destination:
server: https://kubernetes.default.svc
namespace: "{{ index .path.segments 2 }}"
ignoreDifferences:
- group: ""
kind: Secret
jsonPointers:
- /data/username
- /data/password
- group: "secrets.hashicorp.com"
kind: VaultStaticSecret
jsonPointers:
- /spec/data
- group: apps
kind: Deployment
jsonPointers:
- /spec/template/spec/containers/0/env
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true

Note valueFiles: ../../values.yaml — every chart under a deployment reads the same values file, two directories up. That is what keeps the shared blocks (global.vault, global.serviceMesh, global.networkPolicy) identical across every chart in the namespace, which several of them require.

The infrastructure charts have an install order of their own

It is not expressed in sync waves, because the four are usually separate Applications a human syncs rather than one set Argo CD orders: Vault first, then Keycloak (its admin credential is seeded into Vault), then the mesh configuration after Istio itself exists and before any namespace is enrolled, and Kyverno at any time. Infrastructure Charts → Order of installation has the reasoning.

ignoreDifferences — why each entry is there​

These are not optional tuning. Without them Argo CD fights the platform and selfHeal never converges.

EntryWhat it prevents
Secret → /data/username, /data/passwordStorage credentials are generated by setup Jobs and rotated through rotationId. Argo CD renders no value for them, so it would see permanent drift and try to revert a credential the running pods are using
VaultStaticSecret → /spec/dataThe Vault Secrets Operator writes the synced payload back onto the resource. That is the operator's output, not desired state
Deployment → /spec/template/spec/containers/0/envEnvironment injected at runtime — including Vault agent values. Reverting it restarts pods in a loop

Add to this list, do not replace it, if your environment injects anything else post-render.

Kyverno needs two extra adaptations​

Both appear in the per-chart example above and are easy to miss:

  • ServerSideDiff=true on the kyverno-infra Application. Kyverno's CRDs are too large for a client-side diff to converge, so without it they report OutOfSync forever even when they are synced.
  • Report-CR exclusions in the argocd-cm ConfigMap, plus an ignoreDifferences rule for aggregated ClusterRoles. See Admission Control and Image Integrity for both.

The AppProject must permit what these deploy​

An ApplicationSet only generates Applications; the AppProject decides what they may create. In a restricted Argo CD setup a Kind the project does not permit fails the sync outright, and an empty clusterResourceWhitelist permits no cluster-scoped resources at all — which stops the very first sync at the Namespace.

A ready-made allow-list, and the destinations these Applications need — including the Vault namespace, where keycloak-infra and vault-secrets-setup run Jobs that are not in their own namespace — is in Cluster Operator → Kubernetes Resources.


Next Steps​

After successfully deploying the OLIVE Platform with Argo CD, proceed to:

Import Required Foundational OLIVE Connectivity Bundle – Complete the platform setup by importing the core configuration packages that enable essential OLIVE functionality.