@yunuseon/kayra 0.0.0-stage → 0.5.0

package/scripts/local/authelia-dev-init.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Generate local Authelia secrets and a dev user database.
+#
+# Mirrors scripts/local/certs.sh: local-only material, generated on demand and
+# gitignored, never committed. Production gets both from Ansible + vault.
+#
+# Usage: bash scripts/local/authelia-dev-init.sh <authelia-dir> <dev-email> <dev-password>
+set -euo pipefail
+
+usage="Usage: authelia-dev-init.sh <authelia-dir> <dev-email> <dev-password>"
+AUTHELIA_DIR="${1:?$usage}"
+DEV_EMAIL="${2:?$usage}"
+DEV_PASSWORD="${3:?$usage}"
+IMAGE="authelia/authelia:4.39.28"
+
+SECRETS_DIR="${AUTHELIA_DIR}/secrets"
+USERS_FILE="${AUTHELIA_DIR}/users_database.yml"
+
+mkdir -p "${SECRETS_DIR}"
+
+for name in session storage_encryption; do
+  target="${SECRETS_DIR}/${name}"
+  if [ ! -s "${target}" ]; then
+    echo "==> Generating ${name}..."
+    openssl rand -hex 32 > "${target}"
+    chmod 600 "${target}"
+  fi
+done
+
+if [ -s "${USERS_FILE}" ]; then
+  echo "==> ${USERS_FILE} exists — leaving it alone."
+  exit 0
+fi
+
+echo "==> Hashing the dev password (argon2id)..."
+# Authelia's own hasher, so parameters always match configuration.yml.
+  # --memory is KiB here, matching the config's `memory:` key exactly.
+HASH="$(docker run --rm "${IMAGE}" \
+  authelia crypto hash generate argon2 \
+    --variant argon2id --iterations 3 --memory 32768 --parallelism 2 \
+    --password "${DEV_PASSWORD}" \
+  | sed 's/^Digest: //')"
+
+cat > "${USERS_FILE}" <<YML
+# Local development only — generated by scripts/local/authelia-dev-init.sh.
+# Production renders this from vault; see the platform Ansible role.
+users:
+  dev:
+    disabled: false
+    displayname: 'Dev'
+    password: '${HASH}'
+    email: '${DEV_EMAIL}'
+    groups: ['admin']
+YML
+chmod 600 "${USERS_FILE}"
+
+echo ""
+echo "Done — dev login: ${DEV_EMAIL} / ${DEV_PASSWORD}"

package/scripts/local/certs.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Generate local-trusted TLS certs (mkcert) for Traefik.
+# Covers `<domain>`, `*.<domain>`, the platform's subdomains and the given ones.
+#
+# Usage: bash scripts/local/certs.sh <domain> <certs-dir> [subdomain…]
+# Output: <certs-dir>/cert.pem, <certs-dir>/key.pem
+#
+# A no-op when the existing cert already covers <domain>. Local dev and the
+# multipass VM share one certs dir with different domains, so "the file exists"
+# is not enough: shipping the local cert to the VM would break every hostname.
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOMAIN="${1:?Usage: certs.sh <domain> <certs-dir> [subdomain…]}"
+CERTS_DIR="${2:?}"
+shift 2
+
+if [ -f "${CERTS_DIR}/key.pem" ] && [ -f "${CERTS_DIR}/cert.pem" ] \
+   && openssl x509 -in "${CERTS_DIR}/cert.pem" -noout -ext subjectAltName | grep -qE "DNS:${DOMAIN}(,|$)"; then
+  exit 0
+fi
+
+if ! command -v mkcert >/dev/null 2>&1; then
+  echo "ERROR: mkcert not installed. Run: brew install mkcert nss && mkcert -install" >&2
+  exit 1
+fi
+
+# First run on this machine? Install the local CA into the system trust store.
+if [ ! -f "$(mkcert -CAROOT)/rootCA.pem" ]; then
+  echo "==> Installing mkcert local CA (one-time, may prompt for sudo)..."
+  mkcert -install
+fi
+
+mkdir -p "${CERTS_DIR}"
+
+# Explicit subdomain SANs alongside the wildcard: Apple's SecureTransport (used
+# by macOS-bundled curl) doesn't match `*.domain` wildcards. Chrome is fine, but
+# pipelines and smoke tests that use system curl break without these.
+NAMES=("${DOMAIN}" "*.${DOMAIN}")
+for sub in $(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}"/hosts.conf) "$@"; do
+  NAMES+=("${sub}.${DOMAIN}")
+done
+# Keep plain localhost working for native (non-compose) dev.
+NAMES+=(localhost "*.localhost" 127.0.0.1 ::1)
+
+echo "==> Generating cert for ${DOMAIN} (${#NAMES[@]} names)..."
+mkcert \
+  -cert-file "${CERTS_DIR}/cert.pem" \
+  -key-file  "${CERTS_DIR}/key.pem" \
+  "${NAMES[@]}"
+
+chmod 644 "${CERTS_DIR}/cert.pem"
+chmod 600 "${CERTS_DIR}/key.pem"
+
+echo "Done — ${CERTS_DIR}/cert.pem + key.pem"

package/scripts/local/home-image.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Builds what a target: home server boots from, since nothing can create it
+# for us: the Ubuntu cloud image, grown to vm.disk, and a seed ISO with the
+# same cloud-init as every other server plus its fixed address. Both go into
+# the hypervisor by hand, once: the image as the VM's disk, the ISO as a CD.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/home-image.sh <server-name>
+# Writes servers/<name>/vm/ (gitignored): <name>.qcow2, seed.iso.
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+name="${1:?Usage: home-image.sh <server-name>}"
+dir="${FLEET_ROOT}/servers/${name}"
+out="${dir}/vm"
+
+# Pinned. Only the first boot uses it; Ansible keeps the server current after.
+image_url=https://cloud-images.ubuntu.com/releases/noble/release-20260926/ubuntu-24.04-server-cloudimg-amd64.img
+image_sha256=6a81c37564db9b1ee84e141922625e1d7c5b389b99bb3c572e0243607d5bb4d2
+
+command -v qemu-img >/dev/null || { echo "ERROR: qemu-img not installed. Run: brew install qemu" >&2; exit 1; }
+
+address="$(yq '.vm.address' "${dir}/vars.yml")"
+gateway="$(yq '.vm.gateway' "${dir}/vars.yml")"
+disk="$(yq '.vm.disk' "${dir}/vars.yml")"
+key="$(sed -n 's/.*ansible_ssh_private_key_file=\([^ ]*\).*/\1/p' "${dir}/inventory.ini" | head -1).pub"
+
+mkdir -p "${out}/seed"
+image="${out}/cloudimg-${image_sha256:0:12}.img"
+if [ ! -f "$image" ]; then
+    curl -fL --progress-bar -o "${image}.part" "$image_url"
+    mv "${image}.part" "$image"
+fi
+echo "${image_sha256}  ${image}" | shasum -a 256 -c --quiet
+
+rm -f "${out}/${name}.qcow2"
+qemu-img convert -O qcow2 "$image" "${out}/${name}.qcow2"
+qemu-img resize -q "${out}/${name}.qcow2" "$disk"
+
+sed -e "s|[$]{hostname}|${name}|" -e "s|[$]{ssh_pubkey}|$(cat "$key")|" \
+    "${KAYRA_ROOT}/cloud-init.yml.tpl" > "${out}/seed/user-data"
+printf 'instance-id: %s\nlocal-hostname: %s\n' "$name" "$name" > "${out}/seed/meta-data"
+cat > "${out}/seed/network-config" <<NETWORK
+version: 2
+ethernets:
+  lan:
+    match: {name: "e*"}
+    addresses: [${address}]
+    routes: [{to: default, via: ${gateway}}]
+    nameservers: {addresses: [${gateway}]}
+NETWORK
+
+rm -f "${out}/seed.iso"
+hdiutil makehybrid -quiet -iso -joliet -default-volume-name cidata -o "${out}/seed.iso" "${out}/seed"
+echo "Built ${out}/${name}.qcow2 (${disk}) and ${out}/seed.iso: import the first as the VM's disk, attach the second as a CD."

package/scripts/local/home-reach.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Can Ansible get into a home machine (target: home)? If not, say why, in the
+# terms of the failures seen there, before Ansible's UNREACHABLE does not.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/home-reach.sh <server-name> <kind>
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+name="${1:?Usage: home-reach.sh <server-name> <kind>}"
+kind="${2:?Usage: home-reach.sh <server-name> <kind>}"
+inv="${FLEET_ROOT}/servers/${name}/inventory.ini"
+field() { sed -n "s/.*${1}=\([^ ]*\).*/\1/p" "$inv" | head -1; }
+host="$(field ansible_host)"
+user="$(field ansible_user)"
+key="$(field ansible_ssh_private_key_file)"
+port="$(field ansible_port)"
+
+if out="$(ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new \
+    -p "${port:-22}" -i "${key/#\~/$HOME}" "${user}@${host}" true 2>&1)"; then
+  exit 0
+fi
+
+echo "ERROR: cannot SSH into ${name} (${user}@${host}):" >&2
+echo "$out" | grep -v '^\*\*' | sed 's/^/  /' >&2
+case "$out" in
+  *"Connection refused"*)
+    if [ "$kind" = nas ]; then
+      echo "  SSH is off: it is on only on demand, for a set time. UGOS: Control Panel → Terminal → SSH on." >&2
+    else
+      echo "  Nothing listens on port ${port:-22}: is the machine up and sshd running?" >&2
+    fi ;;
+  *"Permission denied"*)
+    echo "  The key is refused. Is it in the agent? ssh-add ${key}" >&2
+    if [ "$kind" = nas ]; then
+      echo "  If it is: UGOS resets permissions, and sshd ignores a writable ~/.ssh. On the NAS:" >&2
+      echo "    chmod 755 ~ && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys" >&2
+    fi ;;
+  *"timed out"*|*"No route to host"*|*"not known"*)
+    echo "  ${host} does not answer: is the machine on, and is this Mac on the home network?" >&2 ;;
+esac
+exit 1

package/scripts/local/require-main.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Refuse to change a real server from anything but main as merged.
+#
+# Every kayra command deploys the local checkout, whatever it is. A
+# test server may track a branch (that is how platform changes are tested);
+# every other server is only ever changed from a clean main that matches
+# origin/main, so what runs there is exactly what was reviewed and merged.
+# Uncommitted changes in other servers' folders do not count: a test server's
+# branch pointers must not block a prod deploy.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/require-main.sh <server-name>
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+name="${1:?Usage: require-main.sh <server-name>}"
+target="$(yq '.target' "${FLEET_ROOT}/servers/${name}/server.yml")"
+[ "$target" != "multipass" ] || exit 0
+
+fail() {
+    echo "ERROR: ${name} is a ${target} server and is only changed from main as merged." >&2
+    echo "  $*" >&2
+    exit 1
+}
+
+cd "$FLEET_ROOT"
+branch="$(git branch --show-current)"
+[ "$branch" = "main" ] || fail "The checkout is on '${branch:-a detached HEAD}'. Merge it, then: git switch main && git pull"
+git fetch -q origin main || fail "Could not fetch origin/main to compare against."
+[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] \
+    || fail "Local main differs from origin/main. Pull, and send unpushed commits through a PR."
+
+others=()
+for dir in servers/*/; do
+    [ "$dir" = "servers/${name}/" ] || others+=(":(exclude)${dir}")
+done
+dirty="$(git status --porcelain --untracked-files=no -- . "${others[@]}")"
+[ -z "$dirty" ] || fail "Uncommitted changes would be deployed; commit them through a PR first:
+${dirty}"

package/scripts/local/setup-hosts.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Point <domain> and its subdomains at <ip> in /etc/hosts. Requires sudo.
+# Subdomains: the platform's (hosts.conf) plus the given ones —
+# callers pass their apps' subdomains, as they do to certs.sh.
+#
+# Usage: bash scripts/local/setup-hosts.sh <domain> <ip> [subdomain…]
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOMAIN="${1:?Usage: setup-hosts.sh <domain> <ip>}"
+IP="${2:?Usage: setup-hosts.sh <domain> <ip> [subdomain…]}"
+shift 2
+
+echo "==> Updating /etc/hosts for ${DOMAIN} -> ${IP}..."
+
+if grep -q "${DOMAIN}" /etc/hosts 2>/dev/null; then
+  echo "    Removing old entries..."
+  sudo sed -i.bak "/${DOMAIN}/d" /etc/hosts
+fi
+
+HOSTS=""
+for sub in $(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}"/hosts.conf) "$@"; do
+  HOSTS="${HOSTS} ${sub}.${DOMAIN}"
+done
+
+echo "${IP} ${DOMAIN}${HOSTS}" | sudo tee -a /etc/hosts > /dev/null
+
+echo ""
+echo "Done — /etc/hosts updated:"
+grep "${DOMAIN}" /etc/hosts

package/scripts/server/app-purge

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# =============================================================================
+# app-purge <app> — delete a removed app's Docker volumes, i.e. its data.
+#
+# Refuses while the app is still registered here: purging is the second,
+# deliberate step after `app-remove`, never a way around it.
+#
+# Installed by the platform role at <platform_dir>/bin. Run as root.
+# =============================================================================
+set -euo pipefail
+
+app="${1:?Usage: app-purge <app>}"
+platform_dir="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [ -e "${platform_dir}/jenkins/casc/10-${app}.yaml" ]; then
+    echo "ERROR: ${app} is still registered on this server — remove it from server.yml and run \`kayra apps <server>\` first." >&2
+    exit 1
+fi
+volumes=$(docker volume ls -q --filter "label=com.docker.compose.project=${app}")
+if [ -z "$volumes" ]; then
+    echo "No volumes left for ${app}."
+    exit 0
+fi
+# Word-splitting on purpose: one volume name per line, none contain spaces.
+# shellcheck disable=SC2086
+docker volume rm $volumes

package/scripts/server/app-remove

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# =============================================================================
+# app-remove <app> — take an app off this server, keeping its data.
+#
+# Stops its containers and removes everything the platform set up for it:
+# JCasC fragment, secret files, .env, the Jenkins folder with its jobs and
+# history, the release records (so Rollback no longer offers it). Its images
+# are collected by the next registry GC, since the app is no longer registered.
+#
+# Volumes stay: dropping a line from server.yml must never silently destroy a
+# database. `app-purge <app>` deletes them deliberately.
+#
+# Run by `kayra apps` for every registered app missing from server.yml.
+# Installed by the platform role at <platform_dir>/bin. Run as root.
+# =============================================================================
+set -euo pipefail
+
+app="${1:?Usage: app-remove <app>}"
+platform_dir="$(cd "$(dirname "$0")/.." && pwd)"
+apps_dir="$(sed -n 's/^APPS_DIR=//p' "${platform_dir}/.env")"
+
+docker compose -p "$app" down --remove-orphans
+rm -rf "${platform_dir}/jenkins/casc/10-${app}.yaml" \
+       "${platform_dir}/jenkins-secrets/${app}" \
+       "${apps_dir:?}/${app}"
+# Without its fragment the reload drops the app's credentials.
+"${platform_dir}/bin/jenkins-reload"
+"${platform_dir}/bin/jenkins-api" POST "/job/${app}/doDelete" -o /dev/null || true
+(cd "$platform_dir" && docker compose exec -T jenkins-controller rm -rf "/var/jenkins_home/releases/${app}")
+echo "Removed ${app}. Its volumes are kept — app-purge ${app} deletes them."

package/scripts/server/jenkins-api

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# =============================================================================
+# jenkins-api <METHOD> <path> [curl args…] — one authenticated call to the
+# Jenkins API, from inside the controller (admin credentials from its env,
+# CSRF crumb fetched in the same session). Prints the response body.
+#
+#   jenkins-api GET  '/api/json?tree=jobs[name]'
+#   jenkins-api POST /configuration-as-code/reload
+#
+# Installed by the platform role at <platform_dir>/bin.
+# =============================================================================
+set -euo pipefail
+
+method="${1:?Usage: jenkins-api <METHOD> <path> [curl args…]}"
+path="${2:?}"
+shift 2
+
+cd "$(dirname "$0")/.."
+docker compose exec -T jenkins-controller sh -ec '
+    jar=$(mktemp)
+    trap "rm -f $jar" EXIT
+    auth="${JENKINS_ADMIN_USER}:${JENKINS_ADMIN_PASSWORD}"
+    base=http://127.0.0.1:8080
+    crumb=$(curl -sf -c "$jar" -u "$auth" \
+        "$base/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,\":\",//crumb)")
+    method="$1"; path="$2"; shift 2
+    curl -sf -b "$jar" -u "$auth" -H "$crumb" -X "$method" "$base$path" "$@"
+' sh "$method" "$path" "$@"

package/scripts/server/jenkins-app-apply

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# =============================================================================
+# jenkins-app-apply <app> — the one way an app registers with Jenkins.
+#
+# Reads the app's secrets as KEY=VALUE lines on stdin, writes each to
+# jenkins-secrets/<app>/<KEY> (where its 10-<app>.yaml reads them via
+# ${readFile:/run/app-secrets/<app>/<KEY>}), then runs jenkins-reload.
+#
+# Installed by the platform role at <platform_dir>/bin. Run as root.
+# =============================================================================
+set -euo pipefail
+
+app="${1:?Usage: jenkins-app-apply <app> < secrets.env}"
+platform_dir="$(cd "$(dirname "$0")/.." && pwd)"
+secrets_dir="${platform_dir}/jenkins-secrets/${app}"
+
+# Staged next to the target and swapped in whole, so keys the app no longer
+# declares disappear instead of lingering.
+staging="${secrets_dir}.new"
+rm -rf "$staging"
+mkdir -p "$staging"
+trap 'rm -rf "$staging"' EXIT
+while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in ''|'#'*) continue ;; esac
+    printf '%s' "${line#*=}" > "${staging}/${line%%=*}"
+done
+rm -rf "$secrets_dir"
+mv "$staging" "$secrets_dir"
+trap - EXIT
+# The controller runs as uid 1000 and reads these through a read-only mount.
+chown -R 1000:1000 "$secrets_dir"
+find "$secrets_dir" -type f -exec chmod 0400 {} +
+chmod 0500 "$secrets_dir"
+
+"${platform_dir}/bin/jenkins-reload"
+echo "Applied Jenkins config for ${app}."

package/scripts/server/jenkins-reload

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# =============================================================================
+# jenkins-reload — re-apply every JCasC fragment in jenkins/casc/ in place.
+#
+# Reload, not restart: Jenkins is shared, and recreating the controller for one
+# config change would kill every app's running builds.
+#
+# Installed by the platform role at <platform_dir>/bin.
+# =============================================================================
+set -euo pipefail
+
+"$(dirname "$0")/jenkins-api" POST /configuration-as-code/reload -o /dev/null

package/terraform/modules/hcloud-firewall/main.tf

@@ -0,0 +1,54 @@
+# =============================================================================
+# Hetzner Cloud Firewall Module
+# Creates a firewall with standard web server rules.
+# =============================================================================
+
+terraform {
+  required_providers {
+    hcloud = {
+      source  = "hetznercloud/hcloud"
+      version = "~> 1.45"
+    }
+  }
+}
+
+resource "hcloud_firewall" "this" {
+  name = var.name
+
+  # SSH
+  rule {
+    direction  = "in"
+    protocol   = "tcp"
+    port       = "22"
+    source_ips = var.ssh_allowed_ips
+  }
+
+  # HTTP
+  rule {
+    direction  = "in"
+    protocol   = "tcp"
+    port       = "80"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  # HTTPS
+  rule {
+    direction  = "in"
+    protocol   = "tcp"
+    port       = "443"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  # Anything else the server's kind needs open to the world (e.g. WireGuard).
+  dynamic "rule" {
+    for_each = var.extra_rules
+    content {
+      direction  = "in"
+      protocol   = rule.value.protocol
+      port       = rule.value.port
+      source_ips = ["0.0.0.0/0", "::/0"]
+    }
+  }
+
+  labels = var.labels
+}

package/terraform/modules/hcloud-firewall/outputs.tf

@@ -0,0 +1,9 @@
+output "firewall_id" {
+  description = "Firewall ID"
+  value       = hcloud_firewall.this.id
+}
+
+output "firewall_name" {
+  description = "Firewall name"
+  value       = hcloud_firewall.this.name
+}

package/terraform/modules/hcloud-firewall/variables.tf

@@ -0,0 +1,22 @@
+variable "name" {
+  description = "Firewall name"
+  type        = string
+}
+
+variable "ssh_allowed_ips" {
+  description = "CIDR ranges allowed to SSH (default: anywhere)"
+  type        = list(string)
+  default     = ["0.0.0.0/0", "::/0"]
+}
+
+variable "extra_rules" {
+  description = "Additional inbound rules open to everyone, e.g. [{protocol = \"udp\", port = \"51820\"}]"
+  type        = list(object({ protocol = string, port = string }))
+  default     = []
+}
+
+variable "labels" {
+  description = "Labels to attach to the firewall"
+  type        = map(string)
+  default     = {}
+}

package/terraform/modules/hcloud-server/main.tf

@@ -0,0 +1,62 @@
+# =============================================================================
+# Hetzner Cloud Server Module
+# Provisions a VPS with SSH key and cloud-init.
+# =============================================================================
+
+terraform {
+  required_providers {
+    hcloud = {
+      source  = "hetznercloud/hcloud"
+      version = "~> 1.45"
+    }
+  }
+}
+
+# ---------------------------------------------------------------------------
+# SSH key
+# ---------------------------------------------------------------------------
+resource "hcloud_ssh_key" "deploy" {
+  name       = "${var.name}-deploy"
+  public_key = var.ssh_public_key
+}
+
+# ---------------------------------------------------------------------------
+# Server
+# ---------------------------------------------------------------------------
+resource "hcloud_server" "this" {
+  name        = var.name
+  server_type = var.server_type
+  image       = var.image
+  location    = var.location
+  ssh_keys    = [hcloud_ssh_key.deploy.id]
+
+  firewall_ids = var.firewall_ids
+
+  user_data = templatefile("${path.module}/../../../cloud-init.yml.tpl", {
+    hostname   = var.name
+    ssh_pubkey = var.ssh_public_key
+  })
+
+  labels = var.labels
+
+  # cloud-init runs once, at creation, and Hetzner replaces the server for any
+  # change to these. Editing the template (or adopting a server that was never
+  # created by us) must not destroy it; Ansible converges existing servers.
+  lifecycle {
+    ignore_changes = [user_data, ssh_keys, image]
+  }
+}
+
+# ---------------------------------------------------------------------------
+# Ansible inventory file
+# ---------------------------------------------------------------------------
+resource "local_file" "ansible_inventory" {
+  content = templatefile("${path.module}/templates/inventory.ini.tpl", {
+    hostname     = var.name
+    ssh_host     = hcloud_server.this.ipv4_address
+    ssh_port     = 22
+    ssh_user     = "deploy"
+    ssh_key_path = var.ssh_private_key_path
+  })
+  filename = var.inventory_path
+}

package/terraform/modules/hcloud-server/outputs.tf

@@ -0,0 +1,19 @@
+output "ipv4_address" {
+  description = "Public IPv4 address of the server"
+  value       = hcloud_server.this.ipv4_address
+}
+
+output "server_id" {
+  description = "Hetzner server ID"
+  value       = hcloud_server.this.id
+}
+
+output "server_name" {
+  description = "Server name"
+  value       = hcloud_server.this.name
+}
+
+output "inventory_path" {
+  description = "Path to the generated Ansible inventory"
+  value       = local_file.ansible_inventory.filename
+}

package/terraform/modules/hcloud-server/templates/inventory.ini.tpl

@@ -0,0 +1,5 @@
+[servers]
+${hostname} ansible_host=${ssh_host} ansible_port=${ssh_port} ansible_user=${ssh_user} ansible_ssh_private_key_file=${ssh_key_path}
+
+[servers:vars]
+ansible_ssh_common_args=-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null

package/terraform/modules/hcloud-server/variables.tf

@@ -0,0 +1,50 @@
+variable "name" {
+  description = "Server name"
+  type        = string
+}
+
+variable "server_type" {
+  description = "Hetzner server type (e.g., cx22, cx32)"
+  type        = string
+  default     = "cx22"
+}
+
+variable "image" {
+  description = "OS image"
+  type        = string
+  default     = "ubuntu-24.04"
+}
+
+variable "location" {
+  description = "Hetzner datacenter location"
+  type        = string
+  default     = "nbg1"
+}
+
+variable "ssh_public_key" {
+  description = "SSH public key for the deploy user"
+  type        = string
+}
+
+variable "ssh_private_key_path" {
+  description = "Path to the SSH private key (for inventory generation)"
+  type        = string
+}
+
+variable "firewall_ids" {
+  description = "List of firewall IDs to attach"
+  type        = list(number)
+  default     = []
+}
+
+variable "labels" {
+  description = "Labels to attach to the server"
+  type        = map(string)
+  default     = {}
+}
+
+variable "inventory_path" {
+  description = "Path to write the Ansible inventory file"
+  type        = string
+  default     = "./inventory.ini"
+}