railiance-platform/docs/argocd-gitops.md

ArgoCD GitOps Contract

Railiance ArgoCD is the cluster sync engine. This repo owns only the shared platform contract around GitOps trust, guardrails, and OpenBao-backed secret delivery. Application workload manifests remain in the owning application repos.

Ownership Boundary

railiance-platform owns:

• ArgoCD AppProject guardrails for Railiance tenant workloads.
• The root app-of-apps entrypoint.
• Repository credential registration templates.
• Secret delivery conventions through OpenBao and External Secrets Operator.

Tenant repos own:

• Container images.
• Workload manifests under k8s/railiance/.
• The proposed ArgoCD Application manifest for platform review.
• Application config that contains no secret values.

Cluster/runtime ownership remains outside this repo: installing or upgrading ArgoCD itself belongs with the cluster layer.

Bootstrap Layout

argocd/bootstrap/
  00-railiance-bootstrap-project.yaml
  01-railiance-tenants-project.yaml
  10-railiance-apps-root.application.yaml

argocd/applications/
  *.application.yaml

argocd/repositories/
  *.repository.sops.yaml

The bootstrap is applied once by an operator. If the Git source is private, apply the encrypted railiance-platform repository Secret first so the root Application can sync this repo:

ARGOCD_REPOSITORY_SECRET=argocd/repositories/railiance-platform.repository.sops.yaml \
  make argocd-repo-apply
make argocd-bootstrap-dry-run
make argocd-bootstrap-deploy
make argocd-status

After that, railiance-apps-root syncs tenant Application manifests from argocd/applications/.

Repository Registration

Every Git source repo used by ArgoCD must be registered in the argocd namespace with an ArgoCD repository Secret. Use one read-only deploy token or deploy key per repo unless an operator approves a narrower shared credential model.

Repository credentials are operator credentials, not workload secrets. Store their source material in OpenBao under:

platform/operators/argocd/repositories/<repo-name>

Create an encrypted repository Secret from the matching template:

cp argocd/repositories/issue-core.repository.sops.yaml.template \
  argocd/repositories/issue-core.repository.sops.yaml
sops -e -i argocd/repositories/issue-core.repository.sops.yaml

Apply only encrypted files:

ARGOCD_REPOSITORY_SECRET=argocd/repositories/issue-core.repository.sops.yaml \
  make argocd-repo-apply

Do not commit plaintext deploy tokens, passwords, SSH private keys, OpenBao tokens, or ArgoCD API tokens.

Tenant Application Contract

Tenant Applications are thin routing manifests reviewed into argocd/applications/. The workload source remains in the tenant repo, normally:

k8s/railiance/

Default Application shape:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: example-service
  namespace: argocd
spec:
  project: railiance-tenants
  source:
    repoURL: https://gitea.coulomb.social/coulomb/example-service.git
    targetRevision: main
    path: k8s/railiance
  destination:
    server: https://kubernetes.default.svc
    namespace: example-service
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true
      - PruneLast=true

Use sync waves only for real dependency ordering. Secret delivery resources should sync before Deployments that consume them.

Secret Delivery

OpenBao is the canonical runtime secret custody authority.

Default pattern:

1. Store workload secret material in OpenBao.
2. Use External Secrets Operator to materialize a Kubernetes Secret in the workload namespace.
3. Reference that Kubernetes Secret from the Deployment, Job, or CronJob.

Path convention:

platform/workloads/<namespace>/<service-account>/<secret-name>

Use CSI-mounted files only for workloads that need file references, sharper mount boundaries, or refresh behavior that should not rewrite application manifests. Do not use the OpenBao injector in the current deployment.

For issue-core, the expected custody shape is:

platform/workloads/issue-core/issue-core/issue-core-runtime

with properties such as:

ISSUE_CORE_API_KEY
GITEA_BACKEND_TOKEN

The exact ExternalSecret manifest belongs with issue-core workload manifests, because it is part of that service's runtime deployment.

AppProject Guardrails

railiance-bootstrap allows the root app to manage ArgoCD Application objects in the argocd namespace.

railiance-tenants allows ordinary namespaced workload resources and namespace creation. It does not allow tenant Applications to create CRDs, ClusterRoles, ClusterRoleBindings, or other cluster-admin resources.

If a tenant needs a cluster-scoped platform resource, create a new platform-owned workplan instead of broadening the tenant project by default.

Platform Add-ons

External Secrets Operator is a platform-owned add-on because it installs CRDs, webhooks, and cluster RBAC. Tenant Applications must not install or upgrade it.

The GitOps contract uses:

• railiance-platform-addons AppProject for cluster add-ons.
• external-secrets ArgoCD Application for the public Helm chart.
• openbao-secretstore ArgoCD Application for the OpenBao ClusterSecretStore.
• OpenBao Kubernetes auth role external-secrets-issue-core for the issue-core pilot.

The initial ClusterSecretStore/openbao is intentionally limited to the issue-core namespace. Broaden it only with a new platform review when another tenant is ready to consume OpenBao through ESO.

Configure the OpenBao side without printing token values:

OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token \
  make openbao-configure-external-secrets-issue-core

The helper keeps Kubernetes auth in local-reviewer mode: OpenBao rereads its own mounted service-account token and CA file instead of storing an expiring reviewer JWT.

Then sync ArgoCD and verify:

make argocd-bootstrap-deploy
make argocd-status
kubectl -n external-secrets get deploy,pod
kubectl get clustersecretstore.external-secrets.io openbao