Skip to content

Deployment Overview

This guide covers how to build, push, and deploy applications and infrastructure to the cluster.

High-Level Flow

graph LR
    A["Code in Git"] -->|Commit| B["Build System<br/>(CI)"]
    B -->|Build Image| C["Container Registry<br/>(ghcr.io)"]
    B -->|Update Manifest| D["Git Repository<br/>(kustomization)"]
    C -->|Pull| E["k3s Cluster"]
    D -->|Watch & Reconcile| E

Deployment Methods

Flux watches the repository and automatically reconciles the cluster:

  1. Commit to git — push manifests or image tag updates
  2. Flux detects change — within ~1 minute
  3. Cluster reconciles — pulls new images, applies manifests
  • ✅ Fully automated & declarative
  • ✅ Audit trail (git history)
  • ✅ Pull-based (more secure than push)
  • ✅ Easy rollback (revert git commit)

See Clusters → Flux System

Option 2: Manual kubectl apply

Apply directly using kustomize + kubectl:

# Apply infrastructure base
kustomize build infrastructure/base/traefik-edge | kubectl apply -f -

# Apply a specific app
kubectl apply -k apps/base/mkdocs
  • Development / testing
  • Quick one-off changes
  • Troubleshooting

Option 3: Helm Commands

For Helm releases:

helm repo add myrepo https://charts.example.com
helm upgrade --install myapp myrepo/mychart -f values.yaml

Building Container Images

Docker Build

# Build locally
docker build -t ghcr.io/your-org/app:v1.0.0 -f Dockerfile .

# Push to registry
docker push ghcr.io/your-org/app:v1.0.0

See Building & Pushing Images for details.

CI/CD Pipeline

Recommended: Use GitHub Actions or GitLab CI to:

  1. Test code
  2. Build images on every commit
  3. Push to registry
  4. Update kustomization.yaml or HelmRelease
  5. Commit back to git (or trigger Flux reconciliation)

Applying Manifests

Kustomize

# Preview output
kustomize build apps/production

# Apply to cluster
kustomize build apps/production | kubectl apply -f -
# or
kubectl apply -k apps/production

Helm

# Add repo
helm repo add immich https://immich-app.github.io/immich

# Update values
helm upgrade --install immich immich/immich \
  --namespace immich \
  --create-namespace \
  -f values.yaml

Troubleshooting Deployments

Check deployment status

# See rollout history
kubectl -n <namespace> rollout history deployment <app>

# Watch real-time status
kubectl -n <namespace> rollout status deployment <app>

View container logs

# Stream logs from pod
kubectl -n <namespace> logs -f deployment/<app>

# View all events in namespace
kubectl -n <namespace> get events --sort-by='.lastTimestamp'

Rollback a deployment

# See previous versions
kubectl -n <namespace> rollout history deployment/<app>

# Rollback to previous version
kubectl -n <namespace> rollout undo deployment/<app>

# Rollback to specific revision
kubectl -n <namespace> rollout undo deployment/<app> --to-revision=2

Storage & Data

See application-specific docs for:

  • PVC size & storage class
  • Backup policies
  • Data migration

Next Steps