tegwick
64d7c18c3f
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.
177 lines
4.8 KiB
Markdown
177 lines
4.8 KiB
Markdown
# 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.
|