Kinds do manifesto

# Complete reference for `kind: Secret` — every field of `spec` and every source form.
# A Secret is a bag of KEY=value pairs, encrypted at rest. It is consumed by
# `Container.secret` (env or /run/secrets files), `Volume.<block>.passwordSecret`,
# `Image.pullSecret` and `provision.truenas.*Secret`.
#
# The three sources (stringData, fromEnvFile, fromEnv) can be combined in ONE document;
# they are shown separately below for clarity. Precedence when combined:
# fromEnvFile first, then stringData overrides it (inline wins over the file).
#
#   delonix stack apply -f examples/full-secret.yaml --dry-run
#
# NOTE: there is no `data:` (base64) field — the engine only reads the three below.
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: inline-secret
  labels:                      # free-form labels stored with the resource
    app: demo
  annotations:                 # free-form annotations
    delonix.io/purpose: "example only"
spec:
  # stringData: inline KEY: value pairs. Values are CLEARTEXT in the manifest, so the
  # apply prints a warning — fine for dev, never commit real values.
  stringData:
    password: change-me        # the key `passwordSecret` fields look for
    apiKey: dummy-api-key      # `apiKeySecret` fields look for `apiKey` (or `token`)
    username: demo             # `pullSecret` wants `username` + `password`
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: file-secret
spec:
  # fromEnvFile: load `KEY=value` lines from a .env-style file, keeping the values OUT of
  # the manifest. A relative path is resolved against the manifest's own folder.
  fromEnvFile: ./secret-source.env
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: env-map-secret
spec:
  # fromEnv, mapping form: `<key in the secret>: <environment variable to read>`.
  # The key is what the consumer looks up; the variable is whatever the CI job exports.
  # An unset variable is an ERROR at apply time, never an empty secret.
  fromEnv:
    password: EXAMPLE_DB_PASSWORD
    token: EXAMPLE_API_TOKEN
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: env-list-secret
spec:
  # fromEnv, list form: shorthand when the key name and the variable name are the same.
  fromEnv:
    - DATABASE_URL
    - SENTRY_DSN
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: combined-secret
spec:
  # All three sources at once: the file gives the base, stringData overrides `LOG_LEVEL`,
  # fromEnv adds a value read from the process environment.
  fromEnvFile: ./secret-source.env
  stringData:
    LOG_LEVEL: debug
  fromEnv:
    - EXAMPLE_EXTRA

# kind: Pod — a real multi-container pod: N containers share ONE network namespace
# (same IP, `localhost` between them), plus IPC/UTS (and optionally PID) sharing.
# The schema is the k8s Pod one (`spec.containers[]`, structured ports/env/resources/
# securityContext, pod-level `volumes[]`) plus an engine-specific `network` field.
#
#   delonix stack apply -f examples/full-pod.yaml --dry-run
#   delonix stack validate -f examples/full-pod.yaml
#
# Documents in this file:
#   1. supporting resources (Network, Volumes) referenced by the pods
#   2. `full-pod`      — every pod-level field and every container field
#   3. `shared-pid`    — shareProcessNamespace: true
#   4. `minimal-pod`   — the smallest valid pod
# ---------------------------------------------------------------------------
# 1. Supporting resources
# ---------------------------------------------------------------------------
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: pod-net
spec:
  driver: bridge
---
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: pod-data                        # referenced through `persistentVolumeClaim.claimName`
spec:
  driver: local
---
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: pod-cache                       # referenced through `source`
spec:
  driver: local
---
# ---------------------------------------------------------------------------
# 2. Every field
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata:
  name: full-pod
  namespace: default                    # isolation namespace (a pod is isolated like a container)
  labels:
    app: full-pod
spec:
  # ---- pod-level ----
  network: pod-net                      # delonix extension: SDN network of the pod's shared netns
                                        #   (host | none | <unset> = the default bridge; a custom name selects that network)
  restartPolicy: OnFailure              # Always | OnFailure | Never (the engine spellings always/on-failure/no are also accepted)
  hostname: full-pod-host               # hostname shared by every member (default: the pod name)
  shareProcessNamespace: false          # true => members see each other's processes (see `shared-pid` below)
  hostAliases:                          # extra /etc/hosts entries in every member, k8s shape
    - ip: 10.0.0.9
      hostnames: [legacy-api, legacy-api.internal]
    - ip: 10.0.0.10
      hostnames: [billing]

  # ---- pod-level volumes, referenced by containers[].volumeMounts[].name ----
  volumes:
    - name: site
      hostPath:                         # bind mount of a host directory
        path: /srv/www
    - name: scratch
      emptyDir:                         # ephemeral, backed by tmpfs (host RAM) in this engine
        medium: Memory                  # "" would warn: k8s means node disk there, this engine always uses tmpfs
    - name: data
      persistentVolumeClaim:            # a NAMED volume (a `kind: Volume`), by name
        claimName: pod-data
    - name: cache
      source: pod-cache                 # delonix extension: a named Volume by plain source string

  # ---- members ----
  containers:
    - name: web                         # member name; the container is called <pod>-<name> (default c<index>)
      image: nginx:latest               # REQUIRED
      command: ["/bin/sh", "-c"]        # k8s `command` => overrides the image ENTRYPOINT
      args: ["nginx -g 'daemon off;'"]  # k8s `args`    => overrides the image CMD
      workingDir: /usr/share/nginx/html # directory the process starts in
      ports:
        - containerPort: 80
          hostPort: 8080                # published on the host ONLY when hostPort is set
          protocol: TCP                 # TCP | UDP (default TCP)
          hostIP: 127.0.0.1             # bind address of the published port
        - containerPort: 443            # no hostPort => informational only, not published
      env:
        - name: TZ
          value: Africa/Luanda
        - name: LOG_LEVEL
          value: info
      volumeMounts:
        - name: site
          mountPath: /usr/share/nginx/html
          readOnly: true
        - name: scratch
          mountPath: /tmp/cache
        - name: data
          mountPath: /var/lib/web
        - name: cache
          mountPath: /var/cache/web
      resources:
        limits:                         # enforced as cgroup limits (`requests` are advisory here and not set)
          cpu: "500m"                   # 500m => 0.5 cores
          memory: 256Mi
      securityContext:
        privileged: false
        runAsUser: 101
        readOnlyRootFilesystem: true
        capabilities:
          drop: ["ALL"]
          add: ["NET_BIND_SERVICE"]

    - name: sidecar                     # a second member: reaches `web` on localhost (shared netns)
      image: busybox:latest
      command: ["sh", "-c"]
      args: ["while true; do wget -qO- http://localhost:80/ >/dev/null 2>&1; sleep 10; done"]
      resources:
        limits:
          cpu: "100m"
          memory: 64Mi
---
# ---------------------------------------------------------------------------
# 3. Shared PID namespace: the members see each other's processes
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata:
  name: shared-pid
spec:
  shareProcessNamespace: true
  containers:
    - name: app
      image: busybox:latest
      command: ["sleep", "infinity"]
    - name: debug
      image: busybox:latest
      command: ["sleep", "infinity"]
---
# ---------------------------------------------------------------------------
# 4. Minimal: only `containers[].image` is mandatory
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata:
  name: minimal-pod
spec:
  containers:
    - image: alpine:3.20                # unnamed member => container "minimal-pod-c0"
      command: ["sleep", "infinity"]
# Not set above, and why:
#   spec.detach, spec.expose   are accepted by the schema but a `kind: Pod` ignores them (members are always
#                              started detached and are not auto-registered in the L7 proxy) — use a
#                              HTTPRoute/Ingress towards the pod for L7 exposure.
#   containers[].tty           accepted and ignored (the engine decides tty by attach/detach).
#   resources.requests         advisory only; the engine enforces `limits`.

# kind: Workload — ONE declarative object for every compute type (ADR-0001/0006).
#
#   delonix stack apply -f examples/full-workload.yaml --dry-run    # shows what each Workload lowers to
#   delonix stack validate -f examples/full-workload.yaml
#
# A Workload is sugar: it does not survive the load. `spec.type` picks the target Kind and the block
# named after the type carries EXACTLY that Kind's spec (no field is redefined here):
#
#     type: container  ->  spec.container  ==  kind: Container spec   (full-container.yaml)
#     type: vm         ->  spec.vm          ==  kind: VirtualMachine spec (full-virtualmachine.yaml)
#     type: pod        ->  spec.pod         ==  kind: Pod spec         (full-pod.yaml)
#     type: microvm    ->  spec.microvm     ==  kind: VirtualMachine spec, backend FORCED to cloud-hypervisor
#
# Exactly ONE block, the one matching `type` (any other block is an error). `metadata` (name, namespace,
# labels, annotations) is inherited by the lowered resource. Because each type is an alternative, every
# type gets its own document below; each block is shown with all its fields.
# ---------------------------------------------------------------------------
# Supporting resources
# ---------------------------------------------------------------------------
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: wl-net
spec:
  driver: bridge
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: wl-secret
spec:
  stringData:
    API_TOKEN: example-token-not-real
---
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: wl-data
spec:
  driver: local
---
# ---------------------------------------------------------------------------
# type: container — the FLAT container spec, every field
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-container
  namespace: default                    # inherited by the lowered Container
  labels: { tier: backend }
  annotations: { example.delonix.io/note: lowers-to-container }
spec:
  type: container
  container:
    image: nginx:alpine                 # REQUIRED
    detach: true
    command: ["nginx", "-g", "daemon off;"]
    entrypoint: /docker-entrypoint.sh
    user: "101:101"
    hostname: wl-container-host
    restartPolicy: always
    addHost: ["legacy-api:10.0.0.9"]
    labels: ["team=platform"]
    logDriver: json
    network: wl-net
    ports: ["18090:80"]
    expose: 80
    networkAlias: [wl-web]
    netBps: 10mbit
    netBurst: 20mbit
    memory: 256M
    cpus: "0.5"
    cpuWeight: "200"
    cpuset: "0"
    ioWeight: "100"
    cgroupParent: { name: wl-tier, memoryMax: "1073741824", cpus: "2", pidsMax: "512" }
    readOnly: true
    capDrop: ["ALL"]
    capAdd: ["NET_BIND_SERVICE"]
    securityOpt: ["no-new-privileges"]
    userns: true
    volumes: ["wl-data:/var/lib/app"]
    tmpfs: ["/tmp"]
    env: ["TZ=Africa/Luanda"]
    secret: [wl-secret]
    secretFiles: true
    ulimit: ["nofile=1024:2048"]
    sysctl: ["net.core.somaxconn=1024"]
---
# ---------------------------------------------------------------------------
# type: container — the GROUPED container spec (resources/network/security/storage/env/limits)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-container-grouped
spec:
  type: container
  container:
    image: busybox:latest
    command: ["sleep", "infinity"]
    restartPolicy: unless-stopped       # no | on-failure[:max] | always | unless-stopped
    resources: { memory: 128M, cpus: "0.25", cpuWeight: "100", ioWeight: "50" }
    network: { name: wl-net, alias: [wl-grouped], rateBps: 5mbit, rateBurst: 10mbit }
    security: { readOnly: true, capDrop: [ALL], userns: true }
    storage: { volumes: ["wl-data:/data"], tmpfs: ["/tmp"] }
    env: { vars: ["MODE=grouped"], secrets: [wl-secret], secretFiles: false }
    limits: { ulimit: ["nofile=512:1024"], sysctl: ["net.core.somaxconn=512"] }
---
# ---------------------------------------------------------------------------
# type: pod — a multi-container pod (k8s-shaped), every pod-level field
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-pod
spec:
  type: pod
  pod:
    network: wl-net                     # SDN network of the pod's shared netns
    restartPolicy: OnFailure            # Always | OnFailure | Never
    hostname: wl-pod-host
    shareProcessNamespace: true         # members see each other's processes
    hostAliases:
      - ip: 10.0.0.9
        hostnames: [legacy-api]
    volumes:
      - name: scratch
        emptyDir: { medium: Memory }
      - name: data
        persistentVolumeClaim: { claimName: wl-data }
      - name: host-files
        hostPath: { path: /srv/www }
    containers:
      - name: web
        image: nginx:latest
        command: ["/bin/sh", "-c"]
        args: ["nginx -g 'daemon off;'"]
        workingDir: /usr/share/nginx/html
        ports:
          - { containerPort: 80, hostPort: 18091, protocol: TCP, hostIP: 127.0.0.1 }
        env:
          - { name: TZ, value: Africa/Luanda }
        volumeMounts:
          - { name: scratch, mountPath: /tmp/cache }
          - { name: data, mountPath: /var/lib/web }
          - { name: host-files, mountPath: /usr/share/nginx/html, readOnly: true }
        resources:
          limits: { cpu: "500m", memory: 256Mi }
        securityContext:
          privileged: false
          runAsUser: 101
          readOnlyRootFilesystem: true
          capabilities: { drop: ["ALL"], add: ["NET_BIND_SERVICE"] }
      - name: sidecar
        image: busybox:latest
        command: ["sleep", "infinity"]
---
# ---------------------------------------------------------------------------
# type: vm — a full VirtualMachine spec (libvirt backend), flat shape
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-vm
spec:
  type: vm
  vm:
    disk: delonix-vm-base:ubuntu-24.04
    backend: libvirt                    # `vm` accepts any backend (unlike `microvm`)
    restartPolicy: always
    vcpus: 2
    memory: 4G
    hugepages: false
    cpuAffinity: "0-1"
    network: wl-net
    netMode: nat
    ip: 192.168.122.60
    vnc: true
    hostname: wl-vm
    sshKeys: ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleExampleExampleExampleExampleExample admin@example"]
    userData: "@/etc/delonix/examples/user-data.yaml"
    volumes:
      - { name: wl-data, mountPath: /mnt/data, readOnly: false }
    machine: q35
    cpuModel: host-model
    cpuTopology: { sockets: 1, cores: 2, threads: 1 }
    tpm: true
    video: virtio
    bootOrder: [hd]
    extraDisks:
      - { source: /var/lib/libvirt/images/wl-extra.qcow2, bus: virtio, format: qcow2, readOnly: false, target: vdb }
    extraNics:
      - { type: network, source: default, model: virtio }
    libvirtXmlOverlay:
      - "<memballoon model='virtio'/>"
---
# ---------------------------------------------------------------------------
# type: vm — the GROUPED VirtualMachine spec (resources/network/cloudInit/libvirt)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-vm-grouped
spec:
  type: vm
  vm:
    disk: delonix-vm-base:ubuntu-24.04
    resources: { vcpus: 2, memory: 2G }
    network: { name: wl-net, mode: nat, staticIp: 192.168.122.61 }
    cloudInit: { hostname: wl-vm-grouped }
    libvirt: { backend: libvirt, machine: q35 }
---
# ---------------------------------------------------------------------------
# type: microvm — a VirtualMachine on the microVM hypervisor; the backend is FORCED to cloud-hypervisor
# (writing `backend: libvirt` here is a contradiction and is rejected — use `type: vm` for that)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: wl-microvm
spec:
  type: microvm
  microvm:
    disk: delonix-vm-base:ubuntu-24.04  # needs an image that boots on Cloud Hypervisor (not the libvirt-only k8s golden)
    backend: cloud-hypervisor           # optional: only the value cloud-hypervisor is accepted here
    vcpus: 2
    memory: 2G
    network: wl-net
    firmware: /usr/local/share/delonix/CLOUDHV.fd
    hostname: wl-microvm
    restartPolicy: on-failure
    hugepages: false
    cpuAffinity: "2-3"
    sshKeys: ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleExampleExampleExampleExampleExample admin@example"]

# Complete reference for `kind: Dependency` (alias `KnowDepends`) — DIRECTED reachability
# between workloads. `from` may open connections to `to`; `to` does not initiate towards
# `from`, and `to` stops being exposed to everyone else on the network.
#
# It is sugar: at load each Dependency is rewritten into a `kind: NetworkPolicy` with
# `direction: ingress` on the `to` workload (default-deny + one allow per `from`, naming the
# peer by WORKLOAD so it survives restarts). Several Dependencies for the same `to` accumulate
# and merge into one policy. Run `delonix stack apply --dry-run` to see the real policy.
#
# spec fields: from (required, string), to (string or list), ports (list), proto.
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: appnet }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: db }
spec:
  network: appnet
  containers:
    - name: db
      image: "postgres:16-alpine"
      env:
        - { name: POSTGRES_PASSWORD, value: example }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: cache }
spec:
  network: appnet
  containers:
    - name: cache
      image: "redis:7-alpine"
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: app }
spec:
  network: appnet
  containers:
    - name: app
      image: "alpine:3.19"
      command: ["sleep", "infinity"]
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: worker }
spec:
  network: appnet
  containers:
    - name: worker
      image: "alpine:3.19"
      command: ["sleep", "infinity"]
---
# 1. Every field, `to` as a single name: app may reach db on TCP/5432 only.
apiVersion: networking.delonix.io/v1alpha1
kind: Dependency
metadata: { name: app-knows-db }
spec:
  from: app                    # who INITIATES (the one that "knows")
  to: db                       # the protected target
  ports: ["5432"]              # ports of `to` opened to `from`; empty/omitted = any port
  proto: tcp                   # tcp | udp | any (default any)
---
# 2. `to` as a LIST: one declaration protecting two targets at once.
apiVersion: networking.delonix.io/v1alpha1
kind: Dependency
metadata: { name: app-knows-cache }
spec:
  from: app
  to: [cache, worker]
  ports: ["6379", "9000"]      # several ports
  proto: tcp
---
# 3. Accumulation: a second `from` for the same `to` (db) — merged with document 1,
#    so db accepts both app (5432/tcp) and worker (any port, any protocol).
apiVersion: networking.delonix.io/v1alpha1
kind: Dependency
metadata: { name: worker-knows-db }
spec:
  from: worker
  to: db

# Complete reference for `kind: NetworkRoute` — a DIRECTED path between two NETWORKS.
# The spec has exactly two fields: `from` and `to`. There is no `via`.
#
# A route only says the packet MAY cross between the two bridges; it never says
# it is ALLOWED. Per-workload policy (NetworkPolicy / Dependency / NetworkAccessRule)
# still decides, so the last two documents show the second question answered.
# The identity of a route is the PAIR (from->to), not metadata.name; two documents
# declaring the same pair are refused. `stack apply --prune` closes routes removed
# from the manifest.
---
# Networks the routes connect (referenced by name; they must be declared here).
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: frontend }
spec: { driver: bridge }
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: backend }
spec: { driver: bridge }
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: mgmt }
spec: { driver: bridge }
---
# 1. One-way path: hosts on `frontend` may initiate towards `backend`.
#    Return traffic of those conversations flows; `backend` cannot initiate back.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkRoute
metadata:
  name: frontend-to-backend
  labels:
    purpose: app-traffic     # metadata is free-form; only spec.from/spec.to matter
spec:
  from: frontend             # network that may INITIATE
  to: backend                # network reached
---
# 2. A second, independent pair: the management network may reach both others.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkRoute
metadata: { name: mgmt-to-backend }
spec:
  from: mgmt
  to: backend
---
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkRoute
metadata: { name: mgmt-to-frontend }
spec:
  from: mgmt
  to: frontend
---
# 3. A bidirectional path is two explicit routes (the reverse pair, declared on purpose).
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkRoute
metadata: { name: backend-to-mgmt }
spec:
  from: backend
  to: mgmt
---
# Workloads, so that the "is it allowed?" question below has something to protect.
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: web }
spec:
  network: frontend
  containers:
    - name: web
      image: "alpine:3.19"
      command: ["sleep", "infinity"]
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: api }
spec:
  network: backend
  containers:
    - name: api
      image: "alpine:3.19"
      command: ["sleep", "infinity"]
---
# 4. The 2nd question, in series with the route: is the crossing ACCEPTED by `api`?
#    Without this the path exists but `api` still decides who it accepts.
apiVersion: networking.delonix.io/v1alpha1
kind: Dependency
metadata: { name: web-knows-api }
spec:
  from: web
  to: api
  ports: ["8080"]
  proto: tcp

# Complete reference for `kind: NetworkPolicy` — declarative L4 firewall.
# One document = the DESIRED STATE of ONE direction (`ingress` or `egress`) of ONE
# target. Applying it REPLACES that direction's rules; the other direction is untouched,
# so an ingress and an egress document compose on the same workload. Two documents for
# the same (target, direction) are refused. It only acts on workloads on a custom SDN network.
#
# spec fields: direction, scope, target, defaultPolicy, rules[], allowCidrs,
# fqdnAllowlist, rateLimit. Per-rule fields: proto, port, action, from, fromWorkload,
# to, toWorkload, note. `allowCidrs`/`fqdnAllowlist`/`rateLimit` are only for
# `scope: network` (documents 5 and 6); `rules` is only for `scope: container`.
---
# Resources the policies refer to (must exist in the same manifest).
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: sdn-demo }
spec: { driver: bridge }
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: sdn-locked }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: db }
spec:
  network: sdn-demo
  containers:
    - name: db
      image: "postgres:16-alpine"
      env:
        - { name: POSTGRES_PASSWORD, value: example }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: app }
spec:
  network: sdn-demo
  containers:
    - name: app
      image: "alpine:3.19"
      command: ["sleep", "infinity"]
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: cache }
spec:
  network: sdn-demo
  containers:
    - name: cache
      image: "redis:7-alpine"
---
# 1. INGRESS allowlist (defaultPolicy deny) using every ingress-side rule form.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: db-inbound }
spec:
  direction: ingress           # ingress (inbound) | egress (outbound)
  scope: container             # container (default): `target` is a workload name
  target: db                   # workload the policy protects
  defaultPolicy: deny          # allow | deny when no rule matches (default for scope container: deny)
  rules:
    - proto: tcp               # tcp | udp | any (default any)
      port: "5432"             # a single port
      from: 10.219.0.0/16      # source CIDR
      action: allow            # allow (default) | deny
      note: postgres-from-sdn  # free-text label, shown in listings
    - proto: tcp
      port: "5432"
      fromWorkload: app        # source BY WORKLOAD NAME (resolved to its SDN address at apply;
                               # survives restarts, unlike a CIDR). Exclusive with from/to.
      note: postgres-from-app
    - proto: udp
      port: "8000-8100"        # a port range n-m
      from: 10.219.5.0/24
      note: udp-range
    - proto: any               # any protocol
      port: "*"                # any port
      from: 10.219.9.9/32
      action: deny             # an explicit deny, evaluated by rule order
      note: block-this-host
---
# 2. INGRESS with defaultPolicy allow: only the listed denies apply.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: cache-inbound-open }
spec:
  direction: ingress
  target: cache
  defaultPolicy: allow         # everything not listed is accepted
  rules:
    - port: "6379"             # proto omitted = any
      from: 203.0.113.0/24
      action: deny
      note: no-external-redis
---
# 3. EGRESS allowlist for a workload, with a CIDR, a workload name and a wildcard.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: app-outbound }
spec:
  direction: egress
  target: app
  defaultPolicy: deny
  rules:
    - proto: udp
      port: "53"
      note: dns
    - proto: tcp
      port: "443"
      to: 0.0.0.0/0            # destination CIDR (egress-side counterpart of `from`)
      note: https-anywhere
    - proto: tcp
      port: "5432"
      toWorkload: db           # destination BY WORKLOAD NAME (egress counterpart of fromWorkload)
      note: postgres-to-db
---
# 4. Minimal egress: no rules, default deny => the workload cannot open outbound connections.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: cache-outbound-locked }
spec:
  direction: egress
  target: cache
  defaultPolicy: deny
---
# 5. PER-NETWORK egress (scope: network, egress only): `target` is a NETWORK name.
#    CIDR allowlist + FQDN allowlist (learnt live from DNS) + global L4 rate limit.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: sdn-locked-egress }
spec:
  direction: egress
  scope: network               # container (default) | network
  target: sdn-locked           # network name
  defaultPolicy: deny          # allowCidrs/fqdnAllowlist only make sense with deny
  allowCidrs:                  # destinations allowed besides DNS
    - 10.0.0.0/8
    - 198.51.100.0/24
  fqdnAllowlist:               # hostnames allowed (and *.host), learnt via DNS snooping
    - registry.example.com
    - updates.example.org
  rateLimit:                   # GLOBAL L4 guard of the rootless ingress (not per network)
    connRate: 100              # new connections per second allowed
    connMax: 2000              # maximum concurrent connections
---
# 6. PER-NETWORK egress fully open (defaultPolicy allow, nothing else).
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkPolicy
metadata: { name: sdn-demo-egress-open }
spec:
  direction: egress
  scope: network
  target: sdn-demo
  defaultPolicy: allow

# Complete reference for `kind: Ingress` — the Kubernetes networking.k8s.io/v1 Ingress shape
# (host/path -> backend service). It compiles to the SAME embedded L7 proxy as `kind: HTTPRoute`
# and is composed with every other Ingress/HTTPRoute of the manifest into ONE proxy with a SINGLE
# certificate (no SNI). Backends must be workloads with an IP on a custom SDN network.
# (The L4 firewall that used to live under this Kind is `kind: NetworkPolicy`.)
#
# spec fields used here: entrypoints[] (port, tls), tls[] (secretName), rules[] (host,
# http.paths[] (path, pathType, backend.service (name, port.number))), defaultBackend.service.
# Not shown because they have no effect: `ingressClassName` (the embedded proxy is the only
# class), `tls[].hosts` (reported as not applied), `pathType: Exact` (served as a prefix and
# warned), a `tls` list longer than one (only the first is used) and named ports (`port.name`
# is refused: use `port.number`).
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: sdn-demo }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: web }
spec:
  network: sdn-demo
  containers:
    - name: web
      image: "nginx:alpine"
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: api }
spec:
  network: sdn-demo
  containers:
    - name: api
      image: "caddy:alpine"
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: docs }
spec:
  network: sdn-demo
  containers:
    - name: docs
      image: "httpd:2.4-alpine"
---
# Certificate presented by the TLS listener (placeholders — use a real pair).
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata: { name: shop-tls }
stringData:
  tls_crt: "-----BEGIN CERTIFICATE-----\nplaceholder\n-----END CERTIFICATE-----"
  tls_key: "-----BEGIN PRIVATE KEY-----\nplaceholder\n-----END PRIVATE KEY-----"
---
# 1. Full Ingress: explicit listeners, a TLS certificate, two hosts, several paths and a default backend.
apiVersion: gateway.delonix.io/v1alpha1
kind: Ingress
metadata: { name: shop }
spec:
  entrypoints:                     # delonix extension: listener ports. Omitted = 80 (+443 when tls is set)
    - { port: 80 }
    - { port: 443, tls: true }     # terminate TLS on this port
  tls:                             # a LIST in k8s; this engine serves a single certificate
    - secretName: shop-tls         # kind: Secret with tls_crt/tls_key (or tls.crt/tls.key); omit = self-signed
  rules:
    - host: shop.example.ao        # Host header to match; omit = any host
      http:
        paths:
          - path: /
            pathType: Prefix       # matched by prefix
            backend:
              service:
                name: web          # workload name, resolved to its SDN IP at apply
                port:
                  number: 80       # container port (named ports are not supported)
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 8080
    - host: docs.example.ao        # a second host in the same Ingress
      http:
        paths:
          - path: /                # `path` defaults to /
            backend:
              service:
                name: docs
                port:
                  number: 80
  defaultBackend:                  # catch-all when no rule matches
    service:
      name: web
      port:
        number: 80
---
# 2. A minimal second Ingress joining the same proxy: no TLS, no entrypoints (defaults to port 80).
apiVersion: gateway.delonix.io/v1alpha1
kind: Ingress
metadata: { name: status }
spec:
  rules:
    - host: status.example.ao
      http:
        paths:
          - path: /healthz
            backend:
              service:
                name: api
                port:
                  number: 8080

# Complete reference for `kind: KubernetesCluster` — the three modes, one document each.
# `mode` is the discriminator: `kind` (nodes as containers here), `vm` (golden-image VMs),
# `ssh` (remote hosts that already exist). Each mode reads only its own block
# (`kind:`, `vm:`, `ssh:`) plus the common fields.
#
# This Kind is NOT part of `stack apply` (a cluster is a remote procedure, not a node-local
# resource). Apply it with:  delonix cluster apply -f examples/full-kubernetescluster.yaml
# Validate offline with:      delonix manifest validate -f examples/full-kubernetescluster.yaml
---
# 1. mode: kind — a local cluster in containers, no Docker and no `kind` binary needed.
apiVersion: infrastructure.delonix.io/v1alpha1
kind: KubernetesCluster
metadata:
  name: lab-kind
spec:
  mode: kind
  k8sVersion: "1.34"                 # Kubernetes minor version
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
  cni: default                       # default = the node image's CNI (kindnet); none = install none
  controlPlane:
    replicas: 1                      # >1 requires controlPlaneEndpoint
  workers:
    replicas: 1
  kind:                              # only read in mode: kind
    image: kindest/node:v1.34.0      # node image (pin by digest for reproducibility)
    apiServerPort: 6443              # host port for the apiserver
---
# 2. mode: vm — every node is a real microVM from the golden image.
apiVersion: infrastructure.delonix.io/v1alpha1
kind: KubernetesCluster
metadata:
  name: lab-vm
spec:
  mode: vm
  k8sVersion: "1.34"
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
  cni: default
  controlPlane:
    replicas: 1
  workers:
    replicas: 2
  vm:                                # only read in mode: vm
    image: k8s-golden                # tag from `delonix image vm ls` (omit = the only local one)
    network: lab-net                 # network created beforehand
    vcpus: 2                         # per node
    memory: 2G                       # per node
    sshKey: ~/.ssh/id_ed25519        # private key to reach the VMs (omit = a key is generated)
    bootTimeout: 300s                # wait for SSH after boot
---
# 3. mode: ssh — hosts that already exist (bare metal / someone else's VMs), HA control plane.
apiVersion: infrastructure.delonix.io/v1alpha1
kind: KubernetesCluster
metadata:
  name: prod-ssh
spec:
  mode: ssh
  k8sVersion: "1.34"
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
  cni: none                          # bring your own CNI (Cilium, Calico...)
  controlPlaneEndpoint: "k8s-api.example.com:6443"   # REQUIRED with >1 control-plane (LB/VIP)
  controlPlane:
    hosts:                           # `hosts` (not `replicas`): the machines already exist
      - address: 10.0.0.11
      - address: 10.0.0.12
      - address: 10.0.0.13
  workers:
    hosts:
      - address: 10.0.0.21
      - address: 10.0.0.22
  ssh:                               # only read in mode: ssh
    user: delonix                    # needs passwordless sudo on the hosts
    keyPath: ~/.ssh/id_ed25519       # canonical name (`key` is the legacy spelling)
    port: 22
  etcd:
    mode: stacked                    # etcd on the control-planes (kubeadm default)
---
# 4. mode: ssh with a dedicated external etcd cluster (own CA, odd number of members).
apiVersion: infrastructure.delonix.io/v1alpha1
kind: KubernetesCluster
metadata:
  name: prod-ssh-etcd
spec:
  mode: ssh
  k8sVersion: "1.34"
  cni: none
  controlPlaneEndpoint: "k8s-api.example.com:6443"
  controlPlane:
    hosts:
      - address: 10.0.1.11
      - address: 10.0.1.12
      - address: 10.0.1.13
  workers:
    hosts:
      - address: 10.0.1.21
  ssh:
    user: delonix
    keyPath: ~/.ssh/id_ed25519
  etcd:
    mode: external                   # external etcd is only accepted with mode: ssh
    hosts:                           # dedicated etcd hosts (odd count; exactly 1 = dev only)
      - address: 10.0.2.11
      - address: 10.0.2.12
      - address: 10.0.2.13

# Complete reference for `kind: Network` — every spec field and every driver form.
# Each document is independent; apply with `delonix stack apply -f full-network.yaml`.
# Fields: driver, subnet, gateway, parent, vni, peers, wgIp (alias wg_ip).
---
# 1. Bridge with every bridge-relevant field spelled out.
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-bridge-full
  labels:
    tier: backend            # free-form labels (ownership stamps are added by stack apply)
  annotations:
    example.io/purpose: "all bridge fields"
spec:
  driver: bridge             # bridge (default) | macvlan | ipvlan | overlay
  subnet: 10.201.0.0/16      # CIDR of the network; omit to auto-pick a free /16
  gateway: 10.201.0.1        # gateway address; omit to default to .0.1 of the subnet
---
# 2. Bridge with every field omitted — driver defaults to bridge, subnet is auto-picked.
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-bridge-default
spec: {}
---
# 3. Overlay (VXLAN) between nodes: vni + peers, clear-text.
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-overlay-plain
spec:
  driver: overlay
  vni: 42                    # VXLAN network identifier
  peers:                     # other nodes of the overlay, by underlay IP
    - 192.168.1.11
    - 192.168.1.12
---
# 4. Encrypted overlay (WireGuard transport): peers carry "<ip>=<wg_pubkey>=<wg_ip>".
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-overlay-encrypted
spec:
  driver: overlay
  vni: 77
  wgIp: 10.250.0.1           # this node's WireGuard tunnel IP (alias: wg_ip)
  peers:
    - "192.168.1.11=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==10.250.0.2"
---
# 5. macvlan: containers get an address directly on the parent NIC's L2 segment.
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-macvlan
spec:
  driver: macvlan
  parent: eth0               # host NIC the macvlan sits on
  subnet: 192.168.50.0/24
  gateway: 192.168.50.1
---
# 6. ipvlan: like macvlan but all containers share the parent's MAC.
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: net-ipvlan
spec:
  driver: ipvlan
  parent: eth0
  subnet: 192.168.60.0/24

# Complete reference for `kind: Volume` — every variant of `spec`.
# One Kind, several MUTUALLY EXCLUSIVE shapes (hence one document each):
#   1. local volume            (driver: local, or nothing)
#   2. raw network driver      (driver: nfs + device + mountOptions)
#   3. nfs: / cifs: / webdav:  network share blocks (the block NAME is the type)
#   4. share:                  a quota'd slice of another volume
#   5. provision.truenas:      create the dataset/quota/export on a NAS, then mount it
# `quota` and `alertPct` apply to every shape.
#
#   delonix stack apply -f examples/full-volume.yaml --dry-run
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: nas-creds
spec:
  # Credentials for the network shares below (cleartext only because this is an example).
  stringData:
    password: change-me
    apiKey: dummy-truenas-api-key
---
# 1. Local named volume: data survives `container rm`.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: local-data
  labels:                       # stored on the volume; also carries the stack ownership stamp
    app: demo
  annotations:
    delonix.io/note: "plain local volume"
spec:
  driver: local                 # local (default) | nfs — omit for local
  quota: 2G                     # size cap (monitored when rootless, hard cap as root)
  alertPct: 80                  # usage % above which `ls`/`describe` show WARN (default 90)
---
# 2. Raw driver form: mount an NFS export without the friendly block.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: raw-nfs
spec:
  driver: nfs
  device: "10.0.0.5:/mnt/pool/raw"   # "server:/export"; only with driver: nfs
  mountOptions: "vers=4.1,soft"      # `mount -o` options (alias: options)
---
# 3a. NFS block.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: nfs-media
spec:
  nfs:
    server: 10.0.0.5                 # NAS host or IP (required)
    share: /mnt/pool/media           # export path (required)
    readOnly: false                  # true = mounted read-only
    mountOptions: "vers=4.1,soft"    # extra `mount -o` options
  quota: 500G
  alertPct: 85
---
# 3b. SMB/CIFS block, credentials from a Secret.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: cifs-backups
spec:
  cifs:
    server: nas.local                # required
    share: backups                   # SMB share name, no leading slash (required)
    username: delonix                # SMB user
    passwordSecret: nas-creds        # reads key `password` from this Secret (preferred)
    readOnly: false
    mountOptions: "vers=3.0"
---
# 3c. SMB/CIFS block with an inline password (discouraged; use passwordSecret instead).
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: cifs-inline
spec:
  cifs:
    server: nas.local
    share: scratch
    username: delonix
    password: change-me              # inline alternative to passwordSecret
    readOnly: true
---
# 3d. WebDAV block (Nextcloud/ownCloud).
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: webdav-cloud
spec:
  webdav:
    server: cloud.example.com        # host, or a full URL to override the scheme
    share: /remote.php/dav/files/delonix   # path inside the WebDAV endpoint
    username: delonix
    passwordSecret: nas-creds
    readOnly: false
---
# 4. Share: an isolated, individually quota'd slice of another volume (`nfs-media` above).
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: team-share
  namespace: teamA                   # scopes the name and data dir; omit = unscoped root
spec:
  share:
    from: nfs-media                  # required: the parent volume to carve out of
  quota: 5G                          # soft quota for this slice
  alertPct: 90
---
# 5. Provision on a TrueNAS appliance: creates dataset + quota + owner + NFS export,
#    then mounts what the appliance reported. Authenticate with an API key OR an account.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: truenas-dados
spec:
  provision:
    truenas:
      url: https://192.168.122.83    # required
      apiKeySecret: nas-creds        # Secret with key `apiKey` (or `token`); preferred over an account
      insecureTLS: true              # a stock TrueNAS serves a self-signed certificate
      dataset: tank/dados            # required: <pool>/<name>
      quota: 2G                      # quota ON THE NAS (min 1 GiB)
      owner:
        uid: 1000                    # required inside owner
        gid: 1000                    # required inside owner
        mode: "0770"                 # octal, quoted
      share:                         # drop this block to provision without exporting
        networks: ["192.168.122.0/24"]   # CIDRs allowed to mount (must be non-empty)
        readOnly: false
        maprootUser: root
        maprootGroup: root
---
# 5b. TrueNAS with account credentials instead of an API key.
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: truenas-account
spec:
  provision:
    truenas:
      url: https://192.168.122.83
      username: truenas_admin        # account name
      passwordSecret: nas-creds      # Secret with key `password` (or use inline `password:`)
      insecureTLS: true
      dataset: tank/account

# Complete reference for `kind: Image` — ensure an image is present, either by PULLING it
# or by BUILDING it (`pull` and `build` are mutually exclusive: one document each).
#
#   delonix stack apply -f examples/full-image.yaml --dry-run
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: registry-cred
spec:
  # Registry credentials (`username` + `password`) for a private registry.
  stringData:
    username: demo
    password: change-me
---
# 1. Pull a public image (idempotent).
apiVersion: artifact.delonix.io/v1alpha1
kind: Image
metadata:
  name: alpine
spec:
  pull: alpine:3.19
---
# 2. Pull from a PRIVATE registry, credentials named by the manifest so it also works on a
#    host where nobody ran `delonix image login`. Only meaningful together with `pull`.
apiVersion: artifact.delonix.io/v1alpha1
kind: Image
metadata:
  name: private-app
spec:
  pull: ghcr.io/example/private-app:1.0
  pullSecret: registry-cred
---
# 3. Build from a Delonixfile/Dockerfile with every build option.
apiVersion: artifact.delonix.io/v1alpha1
kind: Image
metadata:
  name: app-built
spec:
  build:
    tag: app:dev                     # required: the tag to produce
    context: .                       # build context directory (default ".")
    file: Delonixfile                # Delonixfile/Dockerfile path (default: ./Delonixfile, then ./Dockerfile)
    target: runtime                  # multi-stage: build up to this stage (name or index)
    platform: linux/amd64            # target architecture, like the CLI's --platform
    noCache: true                    # bypass the layer cache, like --no-cache
    buildArgs:                       # ARG overrides KEY=VALUE (only for ARGs the file declares)
      - VERSION=1.2.3
      - CHANNEL=stable
    secrets:                         # build-time secrets, `id=<name>,src=<path>`; used with
      - id=npmrc,src=./npmrc.txt     #   RUN --mount=type=secret,id=npmrc — never lands in a layer

# kind: VirtualMachine — a declarative VM (libvirt / Cloud Hypervisor / Proxmox backends).
# Every field of `delonix explain VirtualMachine`, in every accepted shape.
#
#   delonix stack apply -f examples/full-virtualmachine.yaml --dry-run
#   delonix stack validate -f examples/full-virtualmachine.yaml
#
# The base disk is a VM image from the local store (`delonix image vm ls`, e.g. built by
# `delonix image vm build` or pulled with `delonix image vm pull`) or a path to a qcow2/raw.
#
# Documents in this file (variants are alternatives, hence separate documents):
#   1. supporting resources: a Volume (9p share) and a Network
#   2. `full-flat`      — FLAT shape, every field the libvirt backend understands
#   3. `full-grouped`   — GROUPED shape (resources/network/boot/cloudInit/libvirt)
#   4. `bridge-vm`      — netMode: bridge on a host bridge (alternative to nat + static ip)
#   5. `direct-kernel`  — direct-kernel boot (kernel/initrd/cmdline) instead of firmware, Cloud Hypervisor
#   6. `firmware-boot`  — explicit UEFI firmware, Cloud Hypervisor
#   7. `prebuilt-seed`  — a ready-made cloud-init seed ISO instead of the generated one
#   8. `raw-domain`     — the full libvirt <domain> XML used verbatim (escape hatch)
#   9. `built-disk`     — the disk is BUILT from a VMfile (spec.build) instead of named (spec.disk)
# ---------------------------------------------------------------------------
# 1. Supporting resources
# ---------------------------------------------------------------------------
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: vm-data                         # shared into the guest over virtio-9p (libvirt backend)
spec:
  driver: local
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: vm-net                          # the SDN network the VM's tap joins (Cloud Hypervisor backend)
spec:
  driver: bridge
---
# ---------------------------------------------------------------------------
# 2. FLAT shape — every field at the top level (libvirt backend)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: full-flat
  namespace: default                    # isolation namespace (enforced on the Cloud Hypervisor backend only)
spec:
  disk: delonix-vm-base:ubuntu-24.04    # base image: a name in the VM image store, or a path (an overlay is made per VM)
  backend: libvirt                      # cloud-hypervisor | libvirt | proxmox (omit = auto-detect / default-backend)
  restartPolicy: always                 # no | on-failure | always
  vcpus: 4                              # omitted => the image's own default, else 1
  memory: 4G                            # "512M" | "2G" | "2Gi" (k8s-style suffix accepted)
  hugepages: false                      # back guest RAM with hugepages
  cpuAffinity: "0-3"                    # pin vCPUs to host CPUs
  network: vm-net                       # SDN network name (declared above; `ingress` is the built-in default when omitted)
  netMode: nat                          # libvirt only: user | nat | bridge   (`nat` gives an observable IP)
  ip: 192.168.122.50                    # static IP: DHCP reservation on the libvirt network (nat mode only)
  vnc: true                             # graphical console (libvirt backend only)
  devices:                              # VFIO PCI passthrough, sysfs path (backend-agnostic)
    - /sys/bus/pci/devices/0000:01:00.0

  # cloud-init: a NoCloud seed ISO is generated from these unless `seed` is given
  hostname: full-flat                   # hostname applied on first boot
  sshKeys:                              # authorized public keys: "ssh-ed25519 AAAA…" or "@/path/to/key.pub"
    - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleExampleExampleExampleExampleExample admin@example"
  userData: "@/etc/delonix/examples/user-data.yaml"   # your own cloud-init user-data (path or @path); replaces the generated one

  # volumes shared into the guest over virtio-9p (`kind: Volume`, by name)
  volumes:
    - name: vm-data
      mountPath: /mnt/data              # where the guest mounts it
      readOnly: false

  # advanced libvirt knobs
  machine: q35                          # machine type (default q35)
  cpuModel: host-passthrough            # host-passthrough (default) | host-model | a named model
  cpuTopology: { sockets: 1, cores: 2, threads: 2 }
  tpm: true                             # emulated TPM 2.0
  video: virtio                         # virtio | qxl | vga | none
  bootOrder: [hd, cdrom]                # OS boot device order
  extraDisks:                           # extra disks beyond the main overlay + seed
    - source: /var/lib/libvirt/images/extra.qcow2
      device: disk                      # disk (default) | cdrom
      bus: virtio                       # virtio (default) | sata | scsi | ide
      format: qcow2                     # qcow2 (default) | raw
      readOnly: false
      target: vdb                       # explicit target dev (auto-assigned when omitted)
  extraNics:                            # extra network interfaces beyond the primary one
    - type: network                     # network (a libvirt network) | bridge (host bridge) | user
      source: default
      model: virtio                     # virtio (default) | e1000 | …
      mac: "52:54:00:12:34:56"          # fixed MAC (random when omitted)
  libvirtXmlOverlay:                    # raw <device> fragments injected before </devices> (TRUSTED manifests only)
    - "<rng model='virtio'><backend model='random'>/dev/urandom</backend></rng>"
---
# ---------------------------------------------------------------------------
# 3. GROUPED shape — the same knobs, organised by concern
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: full-grouped
spec:
  disk: delonix-vm-base:ubuntu-24.04
  restartPolicy: on-failure
  devices: []                           # VFIO PCI passthrough (stays top-level)
  volumes:                              # 9p mounts (stays top-level)
    - { name: vm-data, mountPath: /mnt/data, readOnly: true }
  vnc: true                             # stays top-level

  resources:
    vcpus: 2
    memory: 2G
    hugepages: false
    cpuAffinity: "0-1"

  network:                              # a mapping here (a plain string is the flat form)
    name: vm-net
    mode: nat                           # => netMode
    staticIp: 192.168.122.51            # => ip (nat mode)
    # bridge: br0                       # => bridge (host bridge, bridge mode) — see `bridge-vm`

  cloudInit:
    hostname: full-grouped
    sshKeys: ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleExampleExampleExampleExampleExample admin@example"]
    userData: "@/etc/delonix/examples/user-data.yaml"
    # seed: /path/seed.iso              # prebuilt seed — see `prebuilt-seed`

  libvirt:                              # advanced libvirt knobs
    backend: libvirt
    machine: q35
    cpuModel: host-model
    cpuTopology: { sockets: 1, cores: 2, threads: 1 }
    tpm: false
    video: qxl
    bootOrder: [hd]
    extraDisks:
      - { source: /var/lib/libvirt/images/scratch.raw, format: raw, bus: sata }
    extraNics:
      - { type: bridge, source: br0, model: e1000 }
    xmlOverlay:                         # => libvirtXmlOverlay
      - "<memballoon model='virtio'/>"
    # xml: "<domain …>"                 # => libvirtXml — see `raw-domain`
---
# ---------------------------------------------------------------------------
# 4. Bridge mode: the VM attaches to a host bridge (mutually exclusive with a static `ip`, which is nat-only)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: bridge-vm
spec:
  disk: delonix-vm-base:ubuntu-24.04
  backend: libvirt
  netMode: bridge
  bridge: br0                           # host bridge / libvirt network to attach to
  vcpus: 2
  memory: 2G
---
# ---------------------------------------------------------------------------
# 5. Direct-kernel boot (alternative to firmware): kernel [+ initrd] [+ cmdline] — Cloud Hypervisor
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: direct-kernel
spec:
  disk: delonix-vm-base:fedora-42
  backend: cloud-hypervisor
  network: vm-net
  kernel: /var/lib/delonix/kernels/vmlinuz-6.14.0     # direct kernel boot
  initrd: /var/lib/delonix/kernels/initramfs-6.14.0.img
  cmdline: "console=ttyS0 root=/dev/vda1 rw"          # kernel command line
  vcpus: 2
  memory: 2G
---
# ---------------------------------------------------------------------------
# 6. Explicit UEFI firmware (the usual way to boot a cloud image) — Cloud Hypervisor
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: firmware-boot
spec:
  disk: delonix-vm-base:ubuntu-24.04
  backend: cloud-hypervisor
  network: vm-net
  firmware: /usr/local/share/delonix/CLOUDHV.fd       # UEFI firmware path
  vcpus: 2
  memory: 2G
---
# ---------------------------------------------------------------------------
# 7. A prebuilt cloud-init seed ISO: replaces the generated one (so hostname/sshKeys/userData are not set)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: prebuilt-seed
spec:
  disk: delonix-vm-base:ubuntu-24.04
  seed: /var/lib/delonix/seeds/prebuilt-seed.iso      # NoCloud ISO handed to the guest as-is
---
# ---------------------------------------------------------------------------
# 8. Escape hatch: the whole libvirt <domain> XML, used verbatim (TRUSTED manifests only)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: raw-domain
spec:
  disk: delonix-vm-base:ubuntu-24.04
  backend: libvirt
  libvirtXml: |
    <domain type='kvm'>
      <name>raw-domain</name>
      <memory unit='MiB'>1024</memory>
      <vcpu>1</vcpu>
      <os><type arch='x86_64' machine='q35'>hvm</type></os>
    </domain>
---
# ---------------------------------------------------------------------------
# 9. The disk is BUILT from a VMfile (spec.build) — mutually exclusive with `disk`
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: VirtualMachine
metadata:
  name: built-disk
spec:
  build:
    context: .                          # build context, relative to THIS manifest's folder (default ".")
    file: VMfile                        # the VMfile (default <context>/VMfile)
    tag: built-disk:latest              # tag of the produced image, then used as the VM's disk (default <name>:latest)
    compress: true                      # zstd-compress the result (default true)
    network: false                      # give the build network access (default false: reproducible)
  vcpus: 2
  memory: 2G

# kind: Container — EVERY field of the flat container spec, in every accepted shape.
#
#   delonix stack apply -f examples/full-container.yaml --dry-run
#   delonix stack validate -f examples/full-container.yaml
#
# Layout of this file (one document per variant, separated by `---`):
#   1. supporting resources (Network, Secret, Volume) that the containers reference
#   2. `full-flat`     — the FLAT shape: every field at the top level of `spec`
#   3. `full-grouped`  — the GROUPED shape: resources/network/security/storage/env/limits
#   4. `env-map`       — `env` written as a plain `KEY: value` mapping
#   5. `foreground`    — `detach: false` (synchronous, like `container run` without -d)
#   6. `minimal`       — the only mandatory field (`image`)
#
# The flat and the grouped shape describe the SAME container; they are separate
# documents because they are alternative spellings (a flat key wins over a grouped one
# of the same target if both are present). The k8s-style `spec.containers[]` shape is a
# `kind: Pod` (see full-pod.yaml) — on a `kind: Container` it is a sunset form.
# ---------------------------------------------------------------------------
# 1. Supporting resources
# ---------------------------------------------------------------------------
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata:
  name: app-net
spec:
  driver: bridge
---
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata:
  name: app-secret
spec:
  stringData:
    DB_PASSWORD: change-me-example      # injected as env (or /run/secrets/DB_PASSWORD, see secretFiles)
---
apiVersion: storage.delonix.io/v1alpha1
kind: Volume
metadata:
  name: app-data
spec:
  driver: local
---
# A peer container so `knows:` has something to resolve.
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: peer
spec:
  image: busybox:latest
  command: ["sleep", "infinity"]
  network: app-net
---
# ---------------------------------------------------------------------------
# 2. FLAT shape — every field at the top level
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: full-flat
  namespace: default                    # isolation namespace (containers of other namespaces cannot reach it)
  labels:                               # metadata labels (the engine adds its own delonix.io/* ones)
    tier: frontend
  annotations:
    example.delonix.io/purpose: full-spec-demo
spec:
  image: nginx:alpine                   # REQUIRED — image reference (pulled if missing)
  detach: true                          # run in the background (default true for a manifest)
  command: ["nginx", "-g", "daemon off;"]   # overrides the image CMD
  entrypoint: /docker-entrypoint.sh     # overrides the image ENTRYPOINT ("" clears it)
  user: "101:101"                       # uid[:gid] or user name to run as
  hostname: full-flat-host              # container hostname (default: the container name)
  restartPolicy: on-failure:3           # no | on-failure[:max] | always | unless-stopped (legacy key `restart` also accepted)
  addHost:                              # extra /etc/hosts entries, `name:ip`
    - legacy-api:10.0.0.9
  labels:                               # container labels, `key=value` (spec-level, distinct from metadata.labels)
    - tier=frontend
    - team=platform

  # --- network ---
  network: app-net                      # host | none | <custom network> (custom => own netns on the SDN)
  ports:                                # publish host:container[/proto]; [hostIp:]host:container and ranges work too
    - "127.0.0.1:18080:80"
    - "18443:443/tcp"
    - "19000-19002:9000-9002"
  expose: 80                            # auto-register this HTTP port in the L7 proxy (needs a custom network)
  networkAlias:                         # extra DNS names on the custom network
    - web
    - frontend
  knows:                                # restrict what this container can reach to these peers (directed Dependency)
    - peer
  netBps: 10mbit                        # egress rate limit (needs a custom network)
  netBurst: 20mbit                      # burst for netBps

  # --- resources (cgroup v2) ---
  memory: 256M                          # 64M | 2G | max
  cpus: "0.5"                           # CPU cores
  cpuWeight: "200"                      # relative CPU weight under contention (1-10000)
  cpuset: "0"                           # pin to CPUs, e.g. "0-3" (needs the cpuset controller delegated)
  ioWeight: "100"                       # relative block-I/O weight
  cgroupParent:                         # shared intermediate cgroup bounding a GROUP of containers together
    name: app-tier                      # single safe path segment
    memoryMax: "1073741824"             # aggregate memory ceiling (bytes)
    cpus: "2"                           # aggregate CPU cores
    pidsMax: "512"                      # aggregate process ceiling

  # --- security ---
  readOnly: true                        # read-only rootfs (writes go to tmpfs/volumes)
  capDrop: ["ALL"]                      # capabilities to drop
  capAdd: ["NET_BIND_SERVICE"]          # capabilities to add back
  securityOpt:                          # docker-style security options
    - no-new-privileges
  # apparmor: <profile>                 # AppArmor profile — see the note at the end of this file
  # selinux: <context>                  # SELinux context   — see the note at the end of this file
  userns: true                          # force the subuid user namespace (already default in rootless)

  # --- storage ---
  volumes:                              # named volume or bind mount; optional :ro
    - app-data:/var/lib/app
    - /etc/hostname:/etc/host-name:ro
  tmpfs:                                # in-memory mounts
    - /tmp
    - /run/cache

  # --- environment ---
  env:                                  # KEY=value list
    - TZ=Africa/Luanda
    - LOG_LEVEL=info
  secret:                               # vault secret names, injected as env (or files, below)
    - app-secret
  secretFiles: false                    # true => secrets appear as /run/secrets/<key> instead of env

  # --- misc limits ---
  ulimit:
    - nofile=1024:2048
  sysctl:
    - net.core.somaxconn=1024
  logDriver: json                       # json | cri
---
# ---------------------------------------------------------------------------
# 3. GROUPED shape — the same fields, organised by concern
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: full-grouped
spec:
  image: nginx:alpine
  detach: true
  command: ["nginx", "-g", "daemon off;"]
  entrypoint: /docker-entrypoint.sh
  user: "101:101"
  hostname: full-grouped-host
  restartPolicy: always
  addHost: ["legacy-api:10.0.0.9"]
  labels: ["tier=frontend"]
  logDriver: json

  resources:                            # cgroup v2 limits
    memory: 256M
    cpus: "0.5"
    cpuWeight: "200"
    cpuset: "0"
    ioWeight: "100"
    cgroupParent:
      name: app-tier-grouped
      memoryMax: "1073741824"
      cpus: "2"
      pidsMax: "512"

  network:                              # a mapping here (a plain string is the flat form)
    name: app-net                       # host | none | <custom network>
    ports: ["18081:80"]
    expose: 80                          # auto-register in the L7 proxy
    alias: [web-grouped]                # => networkAlias
    knows: [peer]
    rateBps: 10mbit                     # => netBps
    rateBurst: 20mbit                   # => netBurst

  security:
    privileged: false                   # true => all caps, seccomp off (trusted workloads only)
    readOnly: true
    capAdd: ["NET_BIND_SERVICE"]
    capDrop: ["ALL"]
    securityOpt: ["no-new-privileges"]
    userns: true
    hostPid: false                      # share the HOST pid namespace
    hostIpc: false                      # share the HOST ipc namespace
    detect: false                       # seccomp in log mode: discover the syscalls a workload uses

  storage:
    volumes: ["app-data:/var/lib/app"]
    tmpfs: ["/tmp"]

  env:                                  # grouped env (vars/files/secrets/secretFiles)
    vars: ["TZ=Africa/Luanda"]
    files: []                           # ["./.env"] — env files read at apply time
    secrets: [app-secret]
    secretFiles: true                   # secrets as /run/secrets/<key>

  limits:
    ulimit: ["nofile=1024:2048"]
    sysctl: ["net.core.somaxconn=1024"]
    devices: ["/dev/null:/dev/fuse-demo"]   # extra device nodes
    # gpus: nvidia                      # all | nvidia | dri — see the note at the end of this file
---
# ---------------------------------------------------------------------------
# 4. `env` as a plain KEY: value mapping (what compose/k8s users write)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: env-map
spec:
  image: busybox:latest
  command: ["sleep", "infinity"]
  env:
    POSTGRES_USER: app
    POSTGRES_PASSWORD: example-only
    PORT: 8080                          # non-strings are stringified
---
# ---------------------------------------------------------------------------
# 5. Foreground: detach false blocks apply until the process exits (like `container run`)
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: foreground
spec:
  image: busybox:latest
  command: ["echo", "hello"]
  detach: false
  restartPolicy: "no"
---
# ---------------------------------------------------------------------------
# 6. Minimal: `image` is the only mandatory field
# ---------------------------------------------------------------------------
apiVersion: compute.delonix.io/v1alpha1
kind: Container
metadata:
  name: minimal
spec:
  image: alpine:3.20
# Fields of `delonix explain Container` deliberately NOT set above:
#   apparmor / selinux  host-LSM specific: an unknown AppArmor profile or SELinux context makes the
#                       runtime refuse to start the container on hosts without it; kept as comments.
#   gpus                needs a CDI spec generated by `nvidia-ctk` on the host; refused otherwise.
#   privileged: true   would defeat the hardening shown in full-flat; shown as `false` in the grouped form.
#   hostPid/hostIpc: true  share HOST namespaces — off on purpose.
#   resources.restart   `restart` is only the legacy alias of `restartPolicy`.
# (The `explain` rows `limits`, `resources`, `security`, `storage`, `restart` are the group names / the alias.)

# Complete reference for `kind: HTTPRoute` — embedded L7/HTTP reverse proxy (Gateway API style).
# Routes by Host header and/or path prefix to backend workloads. The proxy runs inside the
# holder netns (it reaches backends by their SDN IP) and publishes the entry ports on the host.
# TLS terminates at the proxy.
#
# ALL HTTPRoute (and Ingress) documents of a manifest are composed into ONE proxy: listeners
# are merged by port (TLS wins on collision), routes are concatenated, and the proxy has a
# SINGLE certificate (no SNI). If any document says `mode: secretRef` that certificate is used
# for every TLS listener; otherwise a self-signed one covering all the hosts is generated.
# Listeners and TLS are fixed at proxy start-up: changing them restarts the proxy (connections
# are cut); changing only rules is a hot reload with the same PID.
#
# spec fields: entrypoints[] (port, tls), tls (mode, secretRef), rules[] (host, paths[] (path, backend (service, port))).
# Backends must be workloads WITH an IP on a custom SDN network (not host/none networking).
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: appnet }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: web }
spec:
  network: appnet
  containers:
    - name: web
      image: "nginx:1.27-alpine"
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: api }
spec:
  network: appnet
  containers:
    - name: api
      image: "hashicorp/http-echo:latest"
      command: ["-listen=:3000", "-text=hello from api"]
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: admin }
spec:
  network: appnet
  containers:
    - name: admin
      image: "hashicorp/http-echo:latest"
      command: ["-listen=:9000", "-text=admin"]
---
# Certificate for the secretRef mode below (PEM under tls.crt / tls.key; tls_crt / tls_key also work).
# Replace the placeholders with a real pair before serving real traffic.
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata: { name: loja-cert }
stringData:
  tls.crt: "-----BEGIN CERTIFICATE-----\nplaceholder\n-----END CERTIFICATE-----"
  tls.key: "-----BEGIN PRIVATE KEY-----\nplaceholder\n-----END PRIVATE KEY-----"
---
# 1. The main route: two listeners, a certificate from a Secret, host + several path prefixes.
apiVersion: gateway.delonix.io/v1alpha1
kind: HTTPRoute
metadata: { name: loja }
spec:
  entrypoints:
    - { port: 80 }                 # plain HTTP listener (tls defaults to false)
    - { port: 443, tls: true }     # TLS terminates here (requires spec.tls)
  tls:
    mode: secretRef                # selfSigned (default, cert generated for the hosts) | secretRef
    secretRef: loja-cert           # kind: Secret holding tls.crt / tls.key
  rules:
    - host: loja.exemplo.ao        # matched against the Host header
      paths:
        - path: /                  # path prefix; the longest prefix wins
          backend: { service: web, port: 80 }
        - path: /api
          backend: { service: api, port: 3000 }
---
# 2. A second document joins the same proxy: a different host and an extra listener.
apiVersion: gateway.delonix.io/v1alpha1
kind: HTTPRoute
metadata: { name: painel }
spec:
  entrypoints:
    - { port: 8080 }               # extra HTTP listener, merged with the ones above
  rules:
    - host: admin.exemplo.ao
      paths:
        - path: /
          backend: { service: admin, port: 9000 }
---
# 3. A rule without `host` matches ANY Host (a catch-all by path); `path` omitted defaults to `/`.
#    No entrypoints given: defaults to port 80 (plus 443 with TLS if `tls` were set).
apiVersion: gateway.delonix.io/v1alpha1
kind: HTTPRoute
metadata: { name: catch-all }
spec:
  rules:
    - paths:
        - backend: { service: web, port: 80 }

# Complete reference for `kind: Gateway` — exposes ONE local TCP port to the public internet
# through a third-party tunnel provider. It only does the outbound transport; point `localPort`
# at the HTTPRoute proxy's listening port to publish many backends behind one public URL.
#
# spec fields: provider* (pinggy | ngrok | cloudflare), localPort*, hostname, token,
# tokenSecretRef, insecureSkipTlsVerify.   (* = required)
# `token` and `tokenSecretRef` are two ways to give the same credential: use ONE per document.
# Only one ngrok tunnel can be alive at a time (its local agent API has a fixed port).
---
# Secret that carries a provider token under the key `token` (placeholder value).
apiVersion: core.delonix.io/v1alpha1
kind: Secret
metadata: { name: tunnel-token }
stringData:
  token: "REPLACE-WITH-PROVIDER-TOKEN"
---
# 1. Minimal: pinggy free tier needs no account and no extra binary.
apiVersion: gateway.delonix.io/v1alpha1
kind: Gateway
metadata: { name: public-min }
spec:
  provider: pinggy
  localPort: 80              # local port to expose (e.g. the HTTPRoute proxy, or a published port)
---
# 2. pinggy with a pro token given literally (works, but prefer tokenSecretRef).
apiVersion: gateway.delonix.io/v1alpha1
kind: Gateway
metadata: { name: public-pinggy-pro }
spec:
  provider: pinggy
  localPort: 8080
  token: "REPLACE-WITH-PINGGY-PRO-TOKEN"
---
# 3. ngrok with a reserved hostname (passed as ngrok's --url) and the token read from a Secret.
apiVersion: gateway.delonix.io/v1alpha1
kind: Gateway
metadata: { name: public-ngrok }
spec:
  provider: ngrok
  localPort: 8080
  hostname: demo.ngrok.app   # custom/reserved hostname (provider-dependent)
  tokenSecretRef: tunnel-token   # kind: Secret whose `token` key holds the authtoken
---
# 4. cloudflare NAMED tunnel: runs `cloudflared tunnel run --token ...` for a tunnel you already
#    created. `hostname` is informational only — the route itself lives in the Cloudflare dashboard.
#    `insecureSkipTlsVerify` skips verification of the LOCAL backend's self-signed certificate
#    (the origin becomes https://localhost:<localPort>); the public URL is always a real certificate.
apiVersion: gateway.delonix.io/v1alpha1
kind: Gateway
metadata: { name: public-cloudflare }
spec:
  provider: cloudflare
  localPort: 8443
  hostname: app.example.com
  tokenSecretRef: tunnel-token
  insecureSkipTlsVerify: true
---
# 5. cloudflare quick tunnel: no token at all (an ephemeral trycloudflare.com URL).
apiVersion: gateway.delonix.io/v1alpha1
kind: Gateway
metadata: { name: public-cloudflare-quick }
spec:
  provider: cloudflare
  localPort: 80

# kind: App — build an application image from source with Cloud Native Buildpacks (no Dockerfile).
#
#   delonix stack apply -f examples/full-app.yaml --dry-run
#   delonix stack validate -f examples/full-app.yaml
#
# Spec fields: `image` (required), `source`, `builder`, `runImage`. The built image lands in the LOCAL
# image store under the tag in `spec.image`; there is no build cache (every apply rebuilds).
# `builder` selects how the stack is built, and each choice is a separate document below:
#   1. builder: auto     — detect the stack (go.mod, package.json, requirements.txt, …), Paketo builder
#   2. builder: heroku   — the Heroku builder family
#   3. custom builder    — any builder image; `runImage` becomes REQUIRED (and is only read here)
#   4. defaults          — only `image`: source ".", builder "auto"
# ---------------------------------------------------------------------------
# 1. Auto-detected stack (Paketo)
# ---------------------------------------------------------------------------
apiVersion: artifact.delonix.io/v1alpha1
kind: App
metadata:
  name: shop-auto
  labels:
    app: shop
spec:
  source: .                             # directory to build; relative to where you RUN the command (not to this file)
  builder: auto                         # auto | heroku | <builder image ref>   (default auto)
  image: shop-auto:latest               # REQUIRED — tag of the built image in the local image store
---
# ---------------------------------------------------------------------------
# 2. Heroku builder family
# ---------------------------------------------------------------------------
apiVersion: artifact.delonix.io/v1alpha1
kind: App
metadata:
  name: shop-heroku
spec:
  source: .
  builder: heroku
  image: shop-heroku:latest
---
# ---------------------------------------------------------------------------
# 3. A custom builder image — the engine does not read a custom builder's metadata to discover its run image,
#    so `runImage` is mandatory here (omitting it is an error), and meaningless with auto/heroku.
# ---------------------------------------------------------------------------
apiVersion: artifact.delonix.io/v1alpha1
kind: App
metadata:
  name: shop-custom
spec:
  source: ./services/shop               # any directory holding the application source
  builder: registry.example.com/buildpacks/builder-jammy-base:latest
  runImage: registry.example.com/buildpacks/run-jammy-base:latest
  image: shop-custom:1.0.0
---
# ---------------------------------------------------------------------------
# 4. Defaults: only the image tag is mandatory
# ---------------------------------------------------------------------------
apiVersion: artifact.delonix.io/v1alpha1
kind: App
metadata:
  name: shop-defaults
spec:
  image: shop-defaults:latest

# Complete reference for `kind: Service` (ADR-0032) — a SET of workloads picked by
# label and published as MULTIPLE DNS `A` records under
# <name>.<namespace>.delonix.internal, in rotating order (DNS round-robin).
# No VIP, no L4 dataplane, no daemon. Membership is recomputed within a DNS-index TTL
# (~2s): a workload added, removed or relabelled shows up without re-applying.
#
# spec fields: selector.matchLabels (all listed labels must match — logical AND) and
# port (the CONTAINER-side port; never a host or VIP port). A selector that is empty or
# matches nothing is not an error: the name resolves to an empty set and apply warns.
# The workloads below carry labels through `kind: Workload` (type: container), which
# lowers to a labelled container.
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: appnet }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: web-1
  labels: { app: web, tier: frontend, track: stable }
spec:
  type: container
  container: { image: "nginx:alpine", network: appnet }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: web-2
  labels: { app: web, tier: frontend, track: canary }
spec:
  type: container
  container: { image: "nginx:alpine", network: appnet }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Workload
metadata:
  name: api-1
  namespace: team-a            # a namespace other than `default`
  labels: { app: api }
spec:
  type: container
  container: { image: "caddy:alpine", network: appnet }
---
# 1. Single-label selector, namespace `default`.
#    Clients resolve web.default.delonix.internal and get web-1 and web-2 in rotation.
apiVersion: networking.delonix.io/v1alpha1
kind: Service
metadata:
  name: web
  namespace: default
spec:
  selector:
    matchLabels:
      app: web                 # every listed label must match
  port: 80                     # container-side port the members listen on
---
# 2. Multi-label selector: narrows the set to the stable track only (here: web-1).
apiVersion: networking.delonix.io/v1alpha1
kind: Service
metadata:
  name: web-stable
spec:                          # namespace omitted = `default`
  selector:
    matchLabels:
      app: web
      track: stable
  port: 80
---
# 3. Service living in another namespace: resolves as api.team-a.delonix.internal.
#    Namespace isolation applies to DNS: other namespaces get NXDOMAIN (except services in `default`).
apiVersion: networking.delonix.io/v1alpha1
kind: Service
metadata:
  name: api
  namespace: team-a
spec:
  selector:
    matchLabels:
      app: api
  port: 8080

# Complete reference for `kind: NetworkAccessRule` — ONE firewall rule per document,
# INCREMENTAL: several rules for the same target accumulate (unlike NetworkPolicy, which
# replaces a whole direction). Removing a document from the manifest and re-applying
# with --prune retires only that rule. Applying the same document again replaces only
# the rule it owns ("the last command wins" for the same match).
#
# spec fields: target*, direction*, port*, action, proto, from   (* = required).
# The identity of the rule is metadata.name. It only acts on workloads on a custom SDN network.
---
apiVersion: networking.delonix.io/v1alpha1
kind: Network
metadata: { name: appnet }
spec: { driver: bridge }
---
apiVersion: compute.delonix.io/v1alpha1
kind: Pod
metadata: { name: web }
spec:
  network: appnet
  containers:
    - name: web
      image: "nginx:alpine"
---
# 1. Every field explicitly set: allow TCP/8080 into `web` from one CIDR.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-8080-from-lan }
spec:
  target: web                # workload the rule applies to
  direction: ingress         # ingress (traffic TO the workload) | egress (traffic FROM it)
  action: allow              # allow (accept, default) | deny (drop)
  proto: tcp                 # tcp | udp | any (default any)
  port: "8080"               # a port, a range "n-m", or "*" (any)
  from: 10.0.0.0/24          # CIDR of the other end (source on ingress); omit = anywhere
---
# 2. Accumulates with rule 1 on the same target: a second, independent ingress rule.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-metrics-from-monitoring }
spec:
  target: web
  direction: ingress
  proto: tcp
  port: "9090"
  from: 10.1.0.0/24
---
# 3. Port range, UDP, defaults for action (allow) and from (anywhere).
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-udp-range }
spec:
  target: web
  direction: ingress
  proto: udp
  port: "5000-5100"
---
# 4. Explicit deny of one abusive source, any protocol, any port.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-block-bad-host }
spec:
  target: web
  direction: ingress
  action: deny
  proto: any
  port: "*"
  from: 203.0.113.7/32
---
# 5. EGRESS: `from` names the DESTINATION CIDR the workload may reach.
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-egress-https }
spec:
  target: web
  direction: egress
  action: allow
  proto: tcp
  port: "443"
  from: 0.0.0.0/0
---
# 6. Minimal form: only the required fields (direction + port + target).
apiVersion: networking.delonix.io/v1alpha1
kind: NetworkAccessRule
metadata: { name: web-minimal }
spec:
  target: web
  direction: egress
  port: "53"