Add ArgoCD GitOps bootstrap contract for railiance01
Define platform-owned AppProjects, root app-of-apps, repository registration templates, and tenant onboarding docs so issue-core can deploy via ArgoCD. Ignore encrypted repository secrets locally and cross-link OpenBao delivery guidance with the new GitOps contract.
This commit is contained in:
176
docs/argocd-gitops.md
Normal file
176
docs/argocd-gitops.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
platform/operators/argocd/repositories/<repo-name>
|
||||
```
|
||||
|
||||
Create an encrypted repository Secret from the matching template:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
k8s/railiance/
|
||||
```
|
||||
|
||||
Default Application shape:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
platform/workloads/issue-core/issue-core/issue-core-runtime
|
||||
```
|
||||
|
||||
with properties such as:
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user