# Getting Started

Set up a Citadel-managed cluster from scratch and deploy your first policies.

## Prerequisites

- macOS or Linux host
- [Rancher Desktop](https://rancherdesktop.io/) installed (`brew install --cask rancher-desktop` on macOS)
- 4+ CPU cores and 8GB+ RAM available
- Python 3.11+

## 1. Install the Package

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

## 2. Bootstrap a K3s Cluster

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

# Install K3s with security-first defaults (requires root)
sudo ./scripts/01-install-k3s.sh

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

After these two scripts, you have a K3s cluster with Cilium replacing kube-proxy and Flannel, plus Hubble for network flow monitoring.

**Verify:**

```bash
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes    # Should show Ready
cilium status        # Should show OK
```

## 3. Deploy the Operator

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

# Install operator + CRDs + default policies
citadel install

# Check health
citadel status
```

This creates:
- `citadel-system` namespace
- 2 CRDs (`NodeTerminationPolicy`, `NamespaceInfrastructure`)
- ServiceAccount + ClusterRole + ClusterRoleBinding
- Operator Deployment (1 replica)
- 6 default NodeTerminationPolicies (4 enabled, 2 opt-in)

## 4. Check Default Policies

```bash
kubectl get nodeterminationpolicies
```

```
NAME                    REASON                                    PRIORITY   ENABLED   MATCHED   TERMINATED   AGE
max-age-48h             Node exceeded 48-hour maximum age         10         true      0         0            30s
disk-pressure           Node under disk pressure                  100        true      0         0            30s
memory-pressure         Node under memory pressure                100        true      0         0            30s
not-ready               Node is not ready                         200        true      0         0            30s
stuck-volume-detector   Stuck volume mount detected on node       150        false     0         0            30s
gpu-health-detector     GPU health check failed on node           150        false     0         0            30s
```

The operator evaluates these every 60 seconds against all cluster nodes.

## 5. Create Your First Custom Policy

```yaml
# my-policy.yaml
apiVersion: citadel.dev/v1alpha1
kind: NodeTerminationPolicy
metadata:
  name: short-lived-nodes
spec:
  reason: "Development nodes recycled every 12 hours"
  priority: 20
  enabled: true
  dryRun: true     # Start with dry-run to see what matches
  selector:
    maxAgeHours: 12
    nodeSelector:
      node-role: dev
  drain:
    timeoutSeconds: 120
```

```bash
kubectl apply -f my-policy.yaml
# Wait 60s for evaluation
kubectl get ntp short-lived-nodes
```

When you're confident the right nodes are matching, set `dryRun: false`.

## 6. Onboard a Namespace

```yaml
# team-infra.yaml
apiVersion: citadel.dev/v1alpha1
kind: NamespaceInfrastructure
metadata:
  name: team-alpha-infra
  namespace: citadel-system
spec:
  targetNamespace: team-alpha
  networkPolicy:
    defaultDeny: true
    allowedPeers: ["shared-services"]
    allowKubeSystem: true
    allowMonitoring: true
  resourceQuota:
    cpu: "4"
    memory: "8Gi"
    pods: "20"
  limitRange:
    defaultCpu: "500m"
    defaultMemory: "512Mi"
```

```bash
kubectl create ns team-alpha
kubectl apply -f team-infra.yaml

# Watch provisioning
kubectl get nsinfra -n citadel-system -w
```

The operator creates CiliumNetworkPolicies, a ResourceQuota, and a LimitRange in `team-alpha`.

## Optional: Additional Infrastructure

```bash
# Monitoring (Prometheus + Grafana)
./scripts/03-install-monitoring.sh

# WireGuard pod-to-pod encryption
sudo ./scripts/06-enable-wireguard.sh

# Audit logging
sudo ./scripts/07-enable-audit-logging.sh

# Data-at-rest encryption
sudo ./scripts/08-enable-encryption.sh

# cert-manager for TLS
./scripts/09-install-cert-manager.sh

# Dex SSO/OIDC
./scripts/10-install-dex.sh
```

## Next Steps

- [CLI Reference](cli-reference.md) — Both CLIs documented
- [Node Lifecycle Operator](operators/node-lifecycle.md) — Policy evaluation, drain, custom probes
- [Namespace Infrastructure Operator](operators/namespace-infra.md) — Network policies, quotas
- [Operations Runbook](operations/runbook.md) — Troubleshooting by failure mode
