The platform ships with a GitOps system pre-configured. Within the values repo, there is a directory named env/manifests/ where any manifest you place is automatically reconciled into the cluster.

The values repository is a Git repository that captures the complete desired state of the platform. Every change made through the platform's web interface or API is committed there automatically, giving you a full audit trail and a single place to inspect or override platform state. ArgoCD watches the values repository continuously and reconciles the cluster to match — no manual apply steps required.

By default, the platform is installed with a lightweight Git server that hosts the values repository. This server does not have web interface but you can interact with local Git client. To obtain the git clone command, open your terminal and execute the following:

kubectl get secret -n apl-secrets apl-git-config -ojsonpath='{.data.gitCloneCmd}' | base64 --decode

Then, perform the git clone command and go to the values directory where you can perform Git operations.

For production environments, it is recommended to use an external Git repository. See BYO Git.

Directory structure

The env/manifests/ directory is organized into two top-level directories:

env/manifests/
  namespaces/
    {namespace}/
      {resource-type}/
  global/
    {resource-type}/

Each directory under namespaces/ maps one-to-one to a Kubernetes namespace and backs a dedicated ArgoCD application — the namespace is created automatically if it does not exist. Subdirectories within it are organizational only; ArgoCD reconciles everything it finds there into that namespace. The global/ directory works the same way but targets no namespace, making it the right place for cluster-scoped resources such as CRDs, ClusterRoles, and StorageClasses.

Deploy addons to any namespace (apl-addons)

Using apl-addons, platform administrators can deploy arbitrary Kubernetes addons to any namespace in the cluster (including cluster-scoped resources such as CRDs, ClusterRoles, and StorageClasses) without being constrained by team-scoped ArgoCD restrictions. This gives admins a supported, first-class way to install custom tooling alongside the platform without workarounds.

How it works

Place ArgoCD Application manifests inside env/manifests/namespaces/apl-addons/ in the values repository. The GitOps system automatically creates a parent ArgoCD Application that watches this directory and reconciles any Application manifests (custom resources) it finds there. Those resources run under a dedicated ArgoCD AppProject (apl-addons) that has no source, destination, or resource-kind restrictions.

The example apl-addons manifest file below demonstrates how to use apl-addons. Set spec.project to apl-addons and spec.destination.namespace to the namespace you want to use. Any corresponding Kubernetes resources will be deployed by ArgoCD to the specified namespace. You can declare additional resources in the env/manifests/namespaces/<targetNamespace>/ directory.

# env/manifests/namespaces/apl-addons/applications/example-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: example-app
spec:
  project: apl-addons
  source:
    <>
  destination:
    server: https://kubernetes.default.svc
    namespace: <targetNamespace>

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - ServerSideApply=true
      - CreateNamespace=true

Permissions and scope

The apl-addons AppProject is intentionally unrestricted:

• Any source repository is permitted.
• Any destination namespace or cluster is permitted.
• Cluster-scoped resources are fully permitted.

Only Application manifests living in the apl-addons namespace may reference this project.

Constraints

• Avoid targeting the argocd namespace as a destination. This is not enforced automatically, but doing so can break platform behavior.
• Image registry policy still applies. The unrestricted project scope does not exempt workloads deployed via apl-addons from Kyverno image registry enforcement. Pods must pull from registries that satisfy the cluster's policy.
• Protection against deletion. The apl-addons AppProject is protected by a ValidatingAdmissionPolicy at the API-server level, preventing accidental deletion.

Operator-owned directories

Directories under namespaces/ that are prefixed with apl- are owned by the platform, with the exception of the apl-addons/ directory. The platform writes into these operator-owned directories and relies on their contents being intact. Two of them carry platform-critical states: apl-secrets/, which holds SealedSecrets (Kubernetes Secrets encrypted for safe storage in Git) written by the platform operator; and apl-users/, which holds user-management objects. Every other namespace directory is user-owned.

🚧

Do not add, edit, or delete files in any apl- prefixed directory, except for within apl-addons. Changes to the other apl- directories may be overwritten by the operator or break platform behavior.

The apl-addons namespace and its corresponding directory in the values repo are an exception to the operator-owned rule: the platform bootstraps the directory, but platform administrators are expected to write its contents.