railiance-platform/workplans/RAILIANCE-WP-0004-argocd-gitops-bootstrap.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated
RAILIANCE-WP-0004	workplan	Establish ArgoCD GitOps bootstrap contract	railiance	railiance-platform	active	codex	railiance	high	4	2026-06-19	2026-06-19

RAILIANCE-WP-0004 - Establish ArgoCD GitOps Bootstrap Contract

Goal

Establish the minimal platform-owned ArgoCD GitOps contract needed for Railiance application teams to deploy through the already-installed ArgoCD instance on railiance01.

This work responds to the issue-core dependency message from 2026-06-18: ArgoCD is installed and healthy on railiance01, but unused. issue-core will be the first tenant Application and needs platform decisions before it can author its workload deployment.

Intent Alignment

INTENT.md defines this repo as the shared platform-services layer: stateful services, secret custody, stable interfaces, and recoverable operational contracts.

ArgoCD itself is not an application, database, or secret store. The work in this repo is therefore intentionally limited to the platform contract around GitOps:

• repository trust and credential registration for ArgoCD;
• AppProject guardrails that keep tenant syncs inside expected boundaries;
• a root app-of-apps entrypoint that provides a stable onboarding surface;
• the OpenBao-backed runtime secret delivery convention tenants must use.

Application workloads, container images, per-service manifests, and business logic remain owned by the tenant repos.

Scope

In scope:

• Define the bootstrap manifests for ArgoCD AppProjects and the root app-of-apps Application.
• Define how Git source repositories are registered without committing credentials.
• Define where tenant Application manifests are placed and how they point back to tenant-owned workload manifests.
• Confirm the runtime secret delivery pattern: OpenBao custody delivered to Kubernetes via External Secrets Operator by default; CSI-mounted files only when a workload requires file references; OpenBao injector remains disabled.
• Provide an issue-core pilot Application example so that repo can author its final manifest against a concrete contract.

Out of scope:

• Installing or upgrading ArgoCD itself; that is cluster/runtime ownership.
• Moving S5 application workload manifests into this repo.
• Storing ArgoCD repository credentials, API tokens, or application secrets in Git, workplans, State Hub, or chat.
• Applying live manifests that require operator-owned credentials.

Decisions

D-01 - Bootstrap Layout

Use this repo only for the platform-owned GitOps bootstrap:

argocd/bootstrap/      AppProjects and root app-of-apps Application
argocd/applications/  thin tenant Application manifests reviewed by platform
argocd/repositories/  SOPS templates for ArgoCD repository Secret objects
docs/argocd-gitops.md GitOps contract and onboarding guidance

The root Application syncs argocd/applications/ from this repo. Tenant Application manifests in that directory point to workload manifests in each tenant repo, normally k8s/railiance/.

D-02 - AppProject Model

Create two AppProjects:

• railiance-bootstrap only allows the root app to manage ArgoCD Application objects in the argocd namespace.
• railiance-tenants allows tenant Applications to sync ordinary namespaced workload resources into their own namespaces, plus namespace creation. It does not grant CRD, ClusterRole, ClusterRoleBinding, or arbitrary cluster-admin authority.

D-03 - Sync Policy

Default tenant Applications use automated sync with prune and self-heal enabled after platform review. Recommended sync options are:

syncPolicy:
  automated:
    prune: true
    selfHeal: true
  syncOptions:
    - CreateNamespace=true
    - ApplyOutOfSyncOnly=true
    - PruneLast=true

Sync waves are reserved for dependency ordering. Platform services and secret delivery resources should sync before workloads that consume them.

D-04 - Secret Delivery

OpenBao remains the canonical runtime secret custody service. For ordinary Kubernetes workloads, use External Secrets Operator to materialize OpenBao values as Kubernetes Secrets. Do not use the OpenBao injector in the current deployment.

Runtime path convention:

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

ArgoCD repository credentials are operator credentials, not workload secrets, and should live under:

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

Current Evidence

• State Hub inbox message d7a18ff9-e6c6-4e44-a39e-78369e530dfc reports ArgoCD is installed and healthy on railiance01, with zero Applications, zero ApplicationSets, zero registered repositories, and only the stock default AppProject.
• INTENT.md and SCOPE.md keep this repo focused on shared platform services and secret custody. This work therefore creates a bootstrap contract and secret-delivery convention, not app workload ownership.
• docs/openbao.md already states the preferred delivery pattern: External Secrets Operator for values that become Kubernetes Secrets, CSI for file-reference workloads, and no OpenBao injector in the current deployment.

Target State

• argocd/bootstrap/ contains the two AppProjects and root app-of-apps Application.
• argocd/applications/ documents the tenant Application contract and includes an issue-core example manifest.
• argocd/repositories/ contains non-secret SOPS templates for ArgoCD repository registration.
• docs/argocd-gitops.md answers the four questions raised by issue-core: repository registration, source layout, sync policy, and secret delivery.
• Make targets exist for dry-run, deploy, status, and SOPS-backed repository secret application.
• issue-core can author its final Application and workload manifests against this contract without waiting for more platform design.

Tasks

T01 - Review intent and scope boundary

id: RAILIANCE-WP-0004-T01
status: done
priority: high

Review INTENT.md, SCOPE.md, existing OpenBao delivery docs, and the issue-core inbox request. Capture the boundary that ArgoCD bootstrap belongs here only as a platform trust and secret-delivery contract.

T02 - Add ArgoCD bootstrap manifests

id: RAILIANCE-WP-0004-T02
status: done
priority: high

Add AppProject manifests and the root app-of-apps Application under argocd/bootstrap/.

Done when the manifests can be rendered by kubectl apply -k and avoid secret material.

T03 - Define tenant onboarding and repository registration

id: RAILIANCE-WP-0004-T03
status: done
priority: high

Add documentation and templates for tenant Applications, per-repo ArgoCD repository Secret registration, and the issue-core pilot example.

T04 - Confirm OpenBao-backed secret delivery

id: RAILIANCE-WP-0004-T04
status: done
priority: high

Document that OpenBao remains the runtime custody authority, External Secrets Operator is the default Kubernetes delivery mechanism, CSI is reserved for file-reference workloads, and the OpenBao injector remains disabled.

T05 - Operator live bootstrap

id: RAILIANCE-WP-0004-T05
status: done
priority: high

Apply the bootstrap and repository credentials to live ArgoCD after these repo changes are merged to the Git source ArgoCD reads and, if the source repo is private, after an operator provides or materializes read-only repository credentials through the approved OpenBao/operator path.

Applied 2026-06-19 on the live ArgoCD cluster (92.205.130.254, default ~/.kube/config). make argocd-bootstrap-dry-run and make argocd-bootstrap-deploy succeeded. Repository registration was skipped because railiance-platform and issue-core Gitea repos are currently public.

Post-bootstrap status:

• railiance-apps-root: Synced / Healthy
• issue-core: OutOfSync / Missing — sync fails because external-secrets.io/ExternalSecret CRD is not installed on the cluster

Do not paste credentials into the workplan, State Hub, or chat.

T06 - Notify first tenant

id: RAILIANCE-WP-0004-T06
status: done
priority: medium

Reply to issue-core with the GitOps contract pointer and confirm that it owns the final issue-core Application proposal and workload manifests. Include the OpenBao path convention for ISSUE_CORE_API_KEY and the Gitea backend token.

State Hub reply: 56df276d-77d0-427f-92a5-a99cacc1290f.