execution_flow.md

KubApp — Execution Flow (How the Platform Comes Alive)

KubApp is a closed-loop GitOps control system.

It does not only "deploy applications".

It continuously converges system reality toward Git-defined intent.

The execution model is:

Terraform → Build → Registry → GitOps → ArgoCD

↑ ↑ ↑

Snapshot ← Verification ← Cluster ← Reconcile ←┘

1. Laptop push ↓
2. GitHub repo updated ↓
3. Build workflow runs ↓
4. Docker images built + pushed ↓
5. Artifacts created ↓
6. update.yml triggered ↓
7. GitOps repo updated + committed again ↓
8. ArgoCD detects Git change ↓
9. Kubernetes updates automatically

1. Developer pushes code ↓
2. Build workflow
   • builds images
   • pushes registry
   • creates artifacts ↓
3. Update workflow
   • reads artifacts
   • updates GitOps repo
   • commits changes ↓
4. ArgoCD
   • detects Git change
   • syncs automatically
   • reports health status ↓
5. Verify workflow
   • uses ArgoCD CLI/API ONLY
   • checks health
   • triggers rollback via Git tag switch

Every stage is deterministic, reversible, and observable.

Git is the brain.

ArgoCD is the actuator.

Kubernetes is the runtime body.

Terraform is the foundation layer.

------------------------------------------------------------

1. INFRASTRUCTURE BOOTSTRAP (TERRAFORM ORIGIN)

------------------------------------------------------------

Everything begins with infrastructure provisioning.

Terraform establishes the physical execution environment:

- VPC + networking topology

- IAM roles and access boundaries

- EKS Kubernetes cluster

- OIDC authentication bridge

- backend state coordination

At this point:

- No applications exist

- No GitOps system is active

- Only raw compute + cluster foundation exists

This stage creates the "empty operating system"

on which the entire platform will run.

Output:

A fully provisioned Kubernetes cluster with no workload logic.

------------------------------------------------------------

2. GITOPS CONTROL PLANE ACTIVATION (BOOTSTRAP PHASE)

------------------------------------------------------------

Once the cluster exists, it is transformed into a GitOps system.

Bootstrap workflow installs:

- ArgoCD (reconciliation engine)

- SOPS + encryption tooling

- cluster identity bindings

- metrics + observability hooks

- GitHub authentication integration

Critical transition happens here:

The cluster stops being "manual infrastructure"

and becomes a continuously reconciled system.

New rule is established:

Git becomes the only valid configuration interface.

------------------------------------------------------------

3. APPLICATION BUILD PHASE (ARTIFACT GENERATION)

------------------------------------------------------------

The system now moves from infrastructure to workload creation.

CI pipeline scans application definitions:

docker//

For each service:

- Docker image is built

- Image is tagged (commit-based + semantic)

- Image is pushed to registry

- Metadata is generated:

- service name

- image reference

- port configuration

- health checks

- runtime flags

Output is NOT deployment.

Output is intent artifacts.

These artifacts become the input for GitOps reconciliation.

------------------------------------------------------------

4. GITOPS REGISTRY GENERATION (INTENT LAYER)

------------------------------------------------------------

After build completion, the system writes a declarative registry:

gitops/registry//*.json

This is the source of truth for what SHOULD exist.

Each entry defines:

- service identity

- image + version

- environment targeting

- runtime metadata

At this stage:

- Nothing is deployed yet

- No Kubernetes changes happen

- This is pure declarative state definition

Rule:

If it is not in the registry, it does not exist in the platform.

------------------------------------------------------------

5. GITOPS MATERIALIZATION (HELM + CONFIG RENDERING)

------------------------------------------------------------

Registry entries are transformed into deployable manifests:

gitops/envs///values.yaml

This step:

- resolves image versions

- injects environment-specific configuration

- aligns runtime parameters

- prepares Kubernetes manifests

Important constraint:

This is still NOT deployment.

This is state compilation.

Git is updated → ArgoCD observes → Kubernetes will later converge

------------------------------------------------------------

6. RECONCILIATION ENGINE (ARGOCD ACTIVATION LOOP)

------------------------------------------------------------

ArgoCD continuously watches:

gitops/envs//**

Once changes appear:

- ArgoCD detects divergence (Git vs Cluster)

- Kubernetes resources are created or updated

- workloads are reconciled in real time

Execution model becomes:

Git change → ArgoCD detection → Kubernetes mutation

No manual intervention exists in this loop.

This is the moment the platform becomes autonomous.

------------------------------------------------------------

7. INGRESS + ROUTING SYNCHRONIZATION

------------------------------------------------------------

Routing is treated as a first-class system, not static config.

The ingress layer enforces:

- every registered service must be routable

- no orphan routes are allowed

- registry is authoritative for traffic mapping

Validation outcomes:

- missing routes → auto-added or flagged

- stale routes → removed or corrected

System rule:

If a service exists → it must be reachable.

If it is reachable → it must exist in registry.

------------------------------------------------------------

8. DRIFT DETECTION (INFRASTRUCTURE + SYSTEM CONSISTENCY)

------------------------------------------------------------

Terraform and runtime state are continuously validated:

- terraform plan -detailed-exitcode

- cluster state comparison

- configuration divergence detection

Classification:

- NO_DRIFT → system aligned

- DRIFT → divergence detected

- ERROR → failure state

Important distinction:

This layer never modifies infrastructure.

It only observes and reports deviation.

------------------------------------------------------------

9. RUNTIME VERIFICATION (SYSTEM CONVERGENCE CHECK)

------------------------------------------------------------

After reconciliation completes, the system enters validation mode.

Checks include:

- Kubernetes health and readiness

- ArgoCD sync status correctness

- service endpoint reachability

- ingress routing validation

- workload stability confirmation

At this stage:

The system is treated as production-critical.

Failure here means:

real system instability

not pipeline failure

Target condition:

Git state == ArgoCD state == Kubernetes state == Network state

------------------------------------------------------------

10. SNAPSHOT + STABILITY ANCHORING

------------------------------------------------------------

Once validation passes, the system locks in a stable state.

It generates:

- deployment snapshot

- full system metadata record

- commit + environment mapping

Then a stability marker is created:

stable---

This represents:

- a full platform convergence point

- not just an application version

- a system-wide known-good state

It becomes the atomic rollback unit of the entire platform.

------------------------------------------------------------

FINAL SYSTEM BEHAVIOR

------------------------------------------------------------

KubApp does not behave like a CI/CD pipeline.

It behaves like a closed-loop control system:

Desired State (Git)

↓

Reconciliation (ArgoCD)

↓

Actual State (Kubernetes)

↓

Validation (Runtime Checks)

↓

Stabilization (Snapshots)

↓

Feedback Loop (Drift Detection)

This loop runs continuously.

Result:

- Infrastructure is self-healing

- Deployments are deterministic

- State is always traceable

- System converges instead of drifting