Initial VPS operations handbook

ansible/roles/matrix_certificate_smoke/defaults/main.yml

@@ -0,0 +1,11 @@
+---
+# A minimal HTTPS placeholder for the explicitly reserved RTC hostname. It also
+# validates the Traefik HTTP-01 certificate path without deploying RTC services.
+matrix_certificate_smoke_enabled: false
+matrix_certificate_smoke_namespace: matrix-system
+matrix_certificate_smoke_name: mrtc-placeholder
+matrix_certificate_smoke_host: mrtc.chans.xyz
+matrix_certificate_smoke_ingress_class: traefik
+matrix_certificate_smoke_cluster_issuer: letsencrypt-prod
+matrix_certificate_smoke_kubeconfig: /etc/rancher/k3s/k3s.yaml
+matrix_certificate_smoke_cleanup: false

ansible/roles/matrix_certificate_smoke/tasks/main.yml

@@ -0,0 +1,63 @@
+---
+- name: Require explicit approval before certificate smoke test
+  ansible.builtin.assert:
+    that:
+      - matrix_certificate_smoke_enabled | bool
+    fail_msg: >-
+      Refusing certificate smoke test changes. Re-run with
+      matrix_certificate_smoke_enabled=true after creating the test DNS record.
+
+- name: Render non-sensitive certificate smoke-test resources
+  ansible.builtin.template:
+    src: smoke.yaml.j2
+    dest: "/etc/rancher/k3s/{{ matrix_certificate_smoke_name }}.yaml"
+    owner: root
+    group: root
+    mode: "0600"
+
+- name: Apply certificate smoke-test resources
+  ansible.builtin.command:
+    argv:
+      - k3s
+      - kubectl
+      - apply
+      - -f
+      - "/etc/rancher/k3s/{{ matrix_certificate_smoke_name }}.yaml"
+  changed_when: false
+
+- name: Wait for smoke-test deployment
+  ansible.builtin.command:
+    argv:
+      - k3s
+      - kubectl
+      - rollout
+      - status
+      - "deployment/{{ matrix_certificate_smoke_name }}"
+      - "--namespace={{ matrix_certificate_smoke_namespace }}"
+      - --timeout=180s
+  changed_when: false
+
+- name: Wait for smoke-test certificate
+  ansible.builtin.command:
+    argv:
+      - k3s
+      - kubectl
+      - wait
+      - --for=condition=Ready
+      - "certificate/{{ matrix_certificate_smoke_name }}-tls"
+      - "--namespace={{ matrix_certificate_smoke_namespace }}"
+      - --timeout=10m
+  changed_when: false
+  when: not (matrix_certificate_smoke_cleanup | bool)
+
+- name: Remove smoke-test resources after verification
+  ansible.builtin.command:
+    argv:
+      - k3s
+      - kubectl
+      - delete
+      - -f
+      - "/etc/rancher/k3s/{{ matrix_certificate_smoke_name }}.yaml"
+      - --ignore-not-found=true
+  changed_when: false
+  when: matrix_certificate_smoke_cleanup | bool

ansible/roles/matrix_certificate_smoke/templates/smoke.yaml.j2

@@ -0,0 +1,82 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ matrix_certificate_smoke_name }}-content
+  namespace: {{ matrix_certificate_smoke_namespace }}
+data:
+  index.html: MatrixRTC is not available yet.
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ matrix_certificate_smoke_name }}
+  namespace: {{ matrix_certificate_smoke_namespace }}
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: {{ matrix_certificate_smoke_name }}
+  template:
+    metadata:
+      labels:
+        app: {{ matrix_certificate_smoke_name }}
+    spec:
+      containers:
+        - name: static
+          image: nginx:1.27.5-alpine
+          ports:
+            - containerPort: 80
+          volumeMounts:
+            - name: content
+              mountPath: /usr/share/nginx/html/index.html
+              subPath: index.html
+              readOnly: true
+          resources:
+            requests:
+              cpu: 10m
+              memory: 32Mi
+            limits:
+              cpu: 50m
+              memory: 64Mi
+      volumes:
+        - name: content
+          configMap:
+            name: {{ matrix_certificate_smoke_name }}-content
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ matrix_certificate_smoke_name }}
+  namespace: {{ matrix_certificate_smoke_namespace }}
+spec:
+  selector:
+    app: {{ matrix_certificate_smoke_name }}
+  ports:
+    - name: http
+      port: 80
+      targetPort: 80
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ matrix_certificate_smoke_name }}
+  namespace: {{ matrix_certificate_smoke_namespace }}
+  annotations:
+    cert-manager.io/cluster-issuer: {{ matrix_certificate_smoke_cluster_issuer }}
+spec:
+  ingressClassName: {{ matrix_certificate_smoke_ingress_class }}
+  tls:
+    - hosts:
+        - {{ matrix_certificate_smoke_host }}
+      secretName: {{ matrix_certificate_smoke_name }}-tls
+  rules:
+    - host: {{ matrix_certificate_smoke_host }}
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ matrix_certificate_smoke_name }}
+                port:
+                  name: http