# Citadel

A lightweight, security-first Kubernetes platform built on K3s and Cilium.

## What is Citadel?

Citadel provides hardened K3s clusters with zero-trust networking, eBPF-based security, ephemeral node lifecycle, and comprehensive observability using open-source tools.

## Core Features

| Feature | Implementation |
|---------|----------------|
| **Zero-Trust Networking** | Cilium with default-deny CiliumNetworkPolicies |
| **Identity-Based Security** | Pod labels + SPIFFE/SPIRE identities |
| **eBPF Datapath** | Cilium replaces kube-proxy with eBPF |
| **Network Observability** | Hubble for L3/L4/L7 flow monitoring |
| **Ephemeral Node Lifecycle** | 48-hour recycling via NodeTerminationPolicy CRDs |
| **Namespace Infrastructure** | Automated network policies, quotas, limits per namespace |
| **Transparent Encryption** | WireGuard pod-to-pod encryption |
| **Mutual Authentication** | Cilium mTLS via SPIRE |
| **Certificate Management** | cert-manager with auto-rotation |
| **Secrets Management** | external-secrets-operator (Vault, AWS, Azure) |
| **Data-at-Rest Encryption** | AES-GCM etcd encryption |
| **Compliance Scanning** | kube-bench CIS + Trivy vulnerability reports |
| **SSO/OIDC** | Dex identity provider |
| **Audit Logging** | Kubernetes API audit logs |

## Quick Start

### Install the package

```bash
pip install jaymd96-citadel-operator              # CLI + kubernetes client
pip install 'citadel-operator[operator]'  # with kopf for running operators
```

### Deploy into a cluster

```bash
# Preview what will be created
citadel manifests

# Install (creates namespace, CRDs, RBAC, Deployment, default policies)
citadel install

# Check health
citadel status

# Remove
citadel uninstall
```

### Infrastructure setup (K3s + Cilium + security stack)

```bash
# Clone the repo (needed for setup scripts)
git clone <repo-url> citadel && cd citadel

# Bootstrap K3s (requires root)
sudo ./scripts/01-install-k3s.sh

# Install Cilium CNI + Hubble
./scripts/02-install-cilium.sh

# Optional: monitoring, encryption, certificates, SSO
./scripts/03-install-monitoring.sh       # Prometheus + Grafana
sudo ./scripts/06-enable-wireguard.sh    # WireGuard encryption
sudo ./scripts/08-enable-encryption.sh   # etcd encryption
./scripts/09-install-cert-manager.sh     # TLS certificates
./scripts/10-install-dex.sh              # SSO/OIDC
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                  Application Workloads                   │
├─────────────────────────────────────────────────────────┤
│         Citadel Operator (citadel-system namespace)      │
│   ┌──────────────────┐  ┌──────────────────────────┐   │
│   │ Lifecycle Operator│  │ Namespace Infra Operator  │   │
│   │ (60s eval timer)  │  │ (300s drift detection)    │   │
│   └──────────────────┘  └──────────────────────────┘   │
├─────────────────────────────────────────────────────────┤
│              Cilium Network Policies                     │
│        (Identity-based, L3/L4/L7, Default Deny)         │
├─────────────────────────────────────────────────────────┤
│           Cilium CNI + eBPF + Hubble + SPIRE            │
│    (Networking, Load Balancing, mTLS, Observability)    │
├─────────────────────────────────────────────────────────┤
│                     K3s Cluster                          │
│   (Lightweight Kubernetes, No Flannel, No kube-proxy)   │
└─────────────────────────────────────────────────────────┘
```

## Two CLIs

| CLI | Purpose | Install |
|-----|---------|---------|
| `citadel` | Deploy and manage the operator in any cluster | `pip install jaymd96-citadel-operator` |
| `./citadel-ctl` | Bootstrap cluster infrastructure (K3s, Cilium, monitoring, security) | Run from repo root |

See [docs/cli-reference.md](docs/cli-reference.md) for full documentation.

## Directory Structure

```
citadel/
├── src/citadel_operator/   # Python package
│   ├── cli/                # `citadel` CLI (install/uninstall/status/manifests)
│   └── k3s/                # Operators, health checks, node management
├── crds/                   # CRD definitions + RBAC + default policies
├── scripts/                # Numbered setup scripts (01–10)
├── policies/               # Cilium network policies (8 files)
├── security/               # TLS, secrets, SSO, compliance configs
├── monitoring/             # Prometheus alerts
├── docs/                   # Full documentation
├── tests/                  # Unit + e2e tests
├── research/               # Technical reference documents
├── Dockerfile              # Operator container image
├── pyproject.toml          # Package metadata (Hatch build)
└── citadel                   # Infrastructure setup CLI
```

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | System design, component map, design principles |
| [Getting Started](docs/getting-started.md) | First-time setup walkthrough |
| [CLI Reference](docs/cli-reference.md) | Both CLIs: `citadel` + `./citadel-ctl` |
| [Node Lifecycle Operator](docs/operators/node-lifecycle.md) | Policy evaluation, drain, custom probes |
| [Namespace Infra Operator](docs/operators/namespace-infra.md) | Network policies, quotas, limits |
| [API Reference](docs/api-reference/) | Python API for all modules (9 files) |
| [Scripts Reference](docs/operations/scripts-reference.md) | Setup scripts (01–10) + node-lifecycle |
| [Network Policies](docs/operations/network-policies.md) | 8 policy files + operator-generated |
| [Monitoring](docs/operations/monitoring.md) | Alerts, dashboards, metrics gap note |
| [Runbook](docs/operations/runbook.md) | Troubleshooting by failure mode |
| [CRD: NodeTerminationPolicy](docs/crds/nodeterminationpolicy.md) | Full spec, examples |
| [CRD: NamespaceInfrastructure](docs/crds/namespaceinfrastructure.md) | Full spec, examples |

## Design Principles

- **Zero-trust by default** — All traffic denied unless explicitly allowed
- **Identity-based security** — Policies use pod labels and SPIFFE identities, not IPs
- **Ephemeral infrastructure** — No node lives longer than 48 hours; replaced, never upgraded
- **Observable** — Full network flow visibility with Hubble + Prometheus + Grafana
- **Lightweight** — Runs on single nodes or small clusters

## License

MIT License — See LICENSE file for details.
