The platform layer that installs, configures, and reconciles all APL components on a Kubernetes cluster. It owns the values repo structure, the GitOps reconciliation loop, and the ArgoCD project model.
Values repo: The single git repository (ENV_DIR) that is the source of truth for all platform configuration, Helm values, and raw Kubernetes manifests. The apl-operator reads from and writes to it; ArgoCD reconciles it continuously.
Avoid: config repo, gitops repo, env repo
Manifests directory: The env/manifests/ subtree of the values repo. The only place in the values repo where raw Kubernetes resource YAMLs live. Reconciled directly by ArgoCD, not by Helmfile.
Avoid: raw manifests, k8s manifests folder
Namespace directory: A subdirectory of env/manifests/namespaces/ whose name matches a Kubernetes namespace. The apl-operator creates one ArgoCD Application per namespace directory that syncs its contents into that namespace.
Global directory: env/manifests/global/ — contains cluster-scoped resources (CRDs, ClusterRoles). Synced by a single ArgoCD Application with no destination namespace.
Operator-owned directory: A namespace directory whose name starts with apl- and whose contents are written exclusively by the apl-operator program (e.g. apl-secrets/, apl-users/). Platform admins must not write to these.
Avoid: system directory, reserved directory
Platform-admin-owned directory: A namespace directory whose name starts with apl- and whose contents are written by human platform admins, not the apl-operator program. apl-addons/ is the only current example. The operator bootstraps the directory but does not manage its contents.
AppProject: An ArgoCD AppProject resource that scopes which source repos, destination namespaces/clusters, and Kubernetes resource types an Application is permitted to use.
Avoid: project, argo project
Team project: An AppProject named team-{id} scoped to a single team namespace. Generated by charts/team-ns/templates/argocd/argocd-project.yaml.
apl-addons project: The AppProject named apl-addons that governs Applications dropped by platform admins. Fully unrestricted: any source repo, any destination namespace, any cluster, any resource type.
gitops-ns Application: An ArgoCD Application named gitops-ns-{namespace} created by the apl-operator for each namespace directory. Syncs all manifests in that directory into the corresponding namespace with prune: true and CreateNamespace: true.
Avoid: parent app, bootstrap app
App-of-Apps: The pattern where one ArgoCD Application manages a directory of other Application CRs. The gitops-ns-apl-addons Application is an App-of-Apps: it syncs Application CRs into the apl-addons namespace, where ArgoCD picks them up via the "app in any namespace" feature.
App in any namespace: The ArgoCD feature (controlled by application.namespaces in argocd-cm) that allows ArgoCD to watch and reconcile Application CRs living in namespaces other than argocd.