Zum Inhalt

k3s-server (Managed Controlplane)

Agent-lose k3s-Controlplane als Workload auf einem Host-Cluster. Ein Pod stellt kube-apiserver, controller-manager, scheduler und (Default) embedded etcd bereit. Worker joinen von außen mit demselben Bootstrap-Token.
Block cargo.ayedo.cloud/ayedo/k8s/k3s-server
Kind k8sapp / flavor k3s
Image rancher/k3s (Tag über config.image, Default folgt app_version)
HA nein — Single-Pod, supports_ha: false
API-Orchestrierung K8sControlplane

Vollständige Block-Doku und Beispiele: polycrate block examples k3s-server bzw. README im Block.

Die Polycrate API steuert denselben Block (Block Rollout, IPAM, DNS api.{workspace}.k8s.{zone}, Join-Tab). CLI und API sind austauschbar — kein anderer Cluster-Typ.

Architektur

Host-Cluster Namespace
├── Deployment k3s-server (replicas=1, Recreate)
│   ├── controlplane   k3s server --disable-agent
│   ├── pod-data-handler  kubeconfig + metrics-tls Secrets
│   └── audit-log      Audit-NDJSON → stdout → VictoriaLogs
├── PVC  /var/lib/rancher/k3s  (TLS, etcd, kubeconfig)
├── Secret token / kubeconfig / metrics-tls
├── Service und/oder Gateway+TLSRoute / Ingress
├── NetworkPolicy
└── VMPodScrape (optional)

Agent, Flannel, Traefik, ServiceLB, kube-proxy und Cloud-Controller sind im Pod aus. CoreDNS und metrics-server bleiben an (Pending, bis Worker joinen).

Features

  • Embedded etcd (Default), optional SQLite oder externer Datastore
  • Secrets encryption at rest (secretbox, Lifecycle-Actions)
  • API Audit Logging (Default an) + Sidecar
  • PSA / EventRateLimit (CIS-aligned Hardening)
  • OIDC am kube-apiserver
  • etcd-Snapshots auf der PVC, optional S3 (k3s.etcd.snapshots.s3)
  • Metriken (etcd, apiserver, controller-manager, scheduler) via VMPodScrape
  • Air-gap: Image, Pull-Secrets, Sidecar überschreibbar
  • Actions: install, uninstall, status, benchmark, secrets-encryption-*

API-Exposure (genau ein Pfad)

ingress.enabled oder loadbalancer.enabled — nicht beides.

Pfad Config Client-URL
Envoy Gateway (empfohlen) ingress.type: gateway https://api.<cluster_domain>:443
NGINX (TLS-Passthrough) ingress.type: nginx wie Gateway, braucht enable_ssl_passthrough
Dedicated LoadBalancer loadbalancer.mode: cluster, provider: cilium | metallb :6443 an der LB-IP

k3s.cluster_domain (API-Default {workspace}.k8s.{zone}) setzt --cluster-domain und leitet den API-Host api.<cluster_domain> ab, wenn kein Hostname gesetzt ist.

CIDR-Allowlist: api_access.whitelist_cidrs (NGINX-Annotation oder Host-NetworkPolicy).

Cilium-LB: Network Access · Ingress & Edge.

Quick Start (CLI)

Host-Cluster braucht eine StorageClass. Envoy: Block envoy mit default_gateway.enabled.

blocks:
  - name: k3s-server
    from: cargo.ayedo.cloud/ayedo/k8s/k3s-server:0.3.0
    kubeconfig:
      from: k8s
    config:
      namespace: k3s-cp
      persistence:
        storage_class: ceph-block
      loadbalancer:
        enabled: false
      ingress:
        enabled: true
        type: gateway
      k3s:
        cluster_domain: "my-ws.k8s.example.com"
        token: "replace-me-token-min-10-chars"

polycrate run k3s-server install
polycrate run k3s-server status

DNS: api.my-ws.k8s.example.com → Envoy shared VIP.

Über die Polycrate API

  1. Region mit Host-Cluster / Workspace
  2. Kubernetes → Controlplanes → New (K8sControlplane)
  3. API setzt Block-Config (Token, cluster_domain, Exposure, delete_namespace: false)
  4. Block Rollout führt install aus
  5. Outcome: verknüpftes K8sCluster; Tab Join mit Token und K3S_URL

Uninstall löscht den Org-Namespace nicht (delete_namespace: false).

Worker Join

curl -sfL https://get.k3s.io | \
  K3S_URL=https://api.<cluster_domain>:6443 \
  K3S_TOKEN=<token> sh -s - \
  --kubelet-arg "cloud-provider=external" \
  --node-label "role=worker"

Token = k3s.token bzw. Join-Tab. Bei Gateway-Edge nutzen Clients oft Port 443 (kubeconfig), Join gegen den vom Block dokumentierten API-Port.

Day-2

Aktion Wie
Status polycrate run k3s-server status oder Controlplane-Detail in der API
Audit-Logs polycrate logs --block k3s-server --query 'kubernetes.container_name:"audit-log"'
Secrets-Key rotieren polycrate run k3s-server secrets-encryption-rotate
etcd-Snapshots PVC unter server/db/snapshots; optional S3-Folder (geteilt mit Velero-Prefix)
Leaf-Certs Auto-Renew beim k3s-Start; CA manuell k3s certificate rotate-ca
Uninstall polycrate run k3s-server uninstall oder Soft-Delete am K8sControlplane

Weiterführend