Migrate to rootful container architecture with infrastructure fact pattern

Major architectural change from rootless user services to system-level (rootful)
containers to enable group-based Unix socket access for containerized applications.

Infrastructure Changes:
- PostgreSQL: Export postgres-clients group GID as Ansible fact
- Valkey: Export valkey-clients group GID as Ansible fact
- Valkey: Add socket-fix service to maintain correct socket group ownership
- Both: Set socket directories to 770 with client group ownership

Authentik Role Refactoring:
- Remove rootless container configuration (subuid/subgid, lingering, user systemd)
- Deploy Quadlet files to /etc/containers/systemd/ (system-level)
- Use dynamic GID facts in container PodmanArgs (--group-add)
- Simplify user creation to system user with infrastructure group membership
- Update handlers for system scope service management
- Remove unnecessary container security options (no user namespace isolation)

Container Template Changes:
- Pod: Remove --userns args, change WantedBy to multi-user.target
- Containers: Replace Annotation with PodmanArgs using dynamic GIDs
- Remove /dev/shm mounts and SecurityLabelDisable (not needed for rootful)
- Change WantedBy to multi-user.target for system services

Documentation Updates:
- Add ADR-005: Rootful Containers with Infrastructure Fact Pattern
- Update ADR-003: Podman + systemd for system-level deployment
- Update authentik-deployment-guide.md for system scope commands
- Update service-integration-guide.md with rootful pattern examples
- Document discarded rootless approach and rationale

Why Rootful Succeeds:
- Direct UID/GID mapping preserves supplementary groups
- Container process groups match host socket group ownership
- No user namespace remapping breaking permissions

Why Rootless Failed (Discarded):
- User namespace UID/GID remapping broke group-based socket access
- Supplementary groups remapped into subgid range didn't match socket ownership
- Even with --userns=host and keep_original_groups, permissions failed

Pattern Established:
- Infrastructure roles create client groups and export GID facts
- Application roles validate facts and consume in container templates
- Rootful containers run as dedicated users with --group-add for socket access
- System-level deployment provides standard systemd service management

Deployment Validated:
- Services in /system.slice/ ✓
- Process groups: 961 (valkey-clients), 962 (postgres-clients), 966 (authentik) ✓
- Socket permissions: 770 with client groups ✓
- HTTP endpoint responding ✓

roles/authentik/defaults/main.yml

@@ -82,24 +82,9 @@ authentik_default_admin_password: "{{ vault_authentik_admin_password }}"
 authentik_container_server_name: "authentik-server"
 authentik_container_worker_name: "authentik-worker"
 
-# Quadlet service directories (USER SCOPE)
-authentik_quadlet_dir: "{{ authentik_user_quadlet_dir }}"
-authentik_user_quadlet_dir: "{{ authentik_home }}/.config/containers/systemd"
-
 # User session variables (set dynamically during deployment)
 authentik_uid: ""
 
-# =================================================================
-# User Namespace Configuration
-# =================================================================
-
-# Subuid/subgid ranges for authentik user containers
-# Range: 200000-265535 (65536 IDs)
-authentik_subuid_start: 200000
-authentik_subuid_size: 65536
-authentik_subgid_start: 200000
-authentik_subgid_size: 65536
-
 # =================================================================
 # Caddy Integration
 # =================================================================
@@ -115,7 +100,9 @@ caddy_user: "caddy"
 
 # PostgreSQL socket configuration (managed by postgresql role)
 postgresql_unix_socket_directories: "/var/run/postgresql"
+postgresql_client_group: "postgres-clients"
 
 # Valkey socket configuration (managed by valkey role)  
 valkey_unix_socket_path: "/var/run/valkey/valkey.sock"
 valkey_password: "{{ vault_valkey_password }}"
+valkey_client_group: "valkey-clients"

roles/authentik/handlers/main.yml

@@ -1,14 +1,9 @@
 ---
-# Authentik Service Handlers (User Scope)
+# Authentik Service Handlers (System Scope)
 
-- name: reload systemd user
+- name: reload systemd
   systemd:
     daemon_reload: true
-    scope: user
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
 
 - name: reload caddy
   systemd:
@@ -19,44 +14,24 @@
   systemd:
     name: "authentik-pod"
     state: restarted
-    scope: user
     daemon_reload: true
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
 
 - name: restart authentik server
   systemd:
     name: "{{ authentik_container_server_name }}"
     state: restarted
-    scope: user
     daemon_reload: true
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
 
 - name: restart authentik worker
   systemd:
     name: "{{ authentik_container_worker_name }}"
     state: restarted
-    scope: user
     daemon_reload: true
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
 
 - name: stop authentik services
   systemd:
     name: "{{ item }}"
     state: stopped
-    scope: user
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
   loop:
     - "{{ authentik_container_worker_name }}"
     - "{{ authentik_container_server_name }}"
@@ -66,12 +41,7 @@
   systemd:
     name: "{{ item }}"
     state: started
-    scope: user
     daemon_reload: true
-  become: true
-  become_user: "{{ authentik_user }}"
-  environment:
-    XDG_RUNTIME_DIR: "/run/user/{{ authentik_uid }}"
   loop:
     - "authentik-pod"
     - "{{ authentik_container_server_name }}"

roles/authentik/tasks/cache.yml

@@ -1,19 +1,12 @@
 ---
 # Cache setup for Authentik - Self-contained socket permissions
 
-- name: Add authentik user to valkey group for socket access
+- name: Add authentik user to Valkey client group for socket access
   user:
     name: "{{ authentik_user }}"
-    groups: valkey
+    groups: "{{ valkey_client_group }}"
     append: true
 
-- name: Ensure authentik can access Valkey socket directory
-  file:
-    path: "{{ valkey_unix_socket_path | dirname }}"
-    mode: '0770'
-    group: valkey
-  become: true
-
 - name: Test Valkey socket connectivity
   command: >
     redis-cli -s {{ valkey_unix_socket_path }}

roles/authentik/tasks/database.yml

@@ -1,19 +1,12 @@
 ---
 # Database setup for Authentik - Self-contained socket permissions
 
-- name: Add authentik user to postgres group for socket access
+- name: Add authentik user to PostgreSQL client group for socket access
   user:
     name: "{{ authentik_user }}"
-    groups: postgres
+    groups: "{{ postgresql_client_group }}"
     append: true
 
-- name: Ensure authentik can access PostgreSQL socket directory
-  file:
-    path: "{{ postgresql_unix_socket_directories }}"
-    mode: '0770'
-    group: postgres
-  become: true
-
 - name: Test PostgreSQL socket connectivity
   postgresql_ping:
     login_unix_socket: "{{ postgresql_unix_socket_directories }}"

roles/authentik/tasks/main.yml

@@ -2,6 +2,16 @@
 # Authentik Authentication Role - Main Tasks
 # Self-contained deployment with Podman and Unix sockets
 
+- name: Validate infrastructure facts are available
+  assert:
+    that:
+      - postgresql_client_group_gid is defined
+      - valkey_client_group_gid is defined
+    fail_msg: |
+      Required infrastructure facts are not available.
+      Ensure PostgreSQL and Valkey roles have run and exported client group GIDs.
+  tags: [validation]
+
 - name: Setup authentik user and container namespaces
   include_tasks: user.yml
   tags: [user, setup]
@@ -18,8 +28,6 @@
   containers.podman.podman_image:
     name: "{{ authentik_image }}:{{ authentik_version }}"
     state: present
-  become: true
-  become_user: "{{ authentik_user }}"
   tags: [containers, image-pull]
 
 - name: Create media directory structure
@@ -48,29 +56,23 @@
     - restart authentik worker
   tags: [config]
 
-- name: Create Quadlet systemd directory (user scope)
+- name: Create Quadlet systemd directory (system scope)
   file:
-    path: "{{ authentik_quadlet_dir }}"
+    path: /etc/containers/systemd
     state: directory
-    owner: "{{ authentik_user }}"
-    group: "{{ authentik_group }}"
     mode: '0755'
 
-- name: Deploy Quadlet pod and container files (user scope)
+- name: Deploy Quadlet pod and container files (system scope)
   template:
     src: "{{ item.src }}"
-    dest: "{{ authentik_quadlet_dir }}/{{ item.dest }}"
-    owner: "{{ authentik_user }}"
-    group: "{{ authentik_group }}"
+    dest: "/etc/containers/systemd/{{ item.dest }}"
     mode: '0644'
   loop:
     - { src: 'authentik.pod', dest: 'authentik.pod' }
     - { src: 'authentik-server.container', dest: 'authentik-server.container' }
     - { src: 'authentik-worker.container', dest: 'authentik-worker.container' }
-  become: true
-  become_user: "{{ authentik_user }}"
   notify:
-    - reload systemd user
+    - reload systemd
     - restart authentik pod
     - restart authentik server  
     - restart authentik worker
@@ -108,22 +110,12 @@
     timeout: 30
   when: valkey_unix_socket_enabled
 
-- name: Ensure systemd user session is started
-  systemd:
-    name: "user@{{ authentik_uid }}.service"
-    state: started
-    scope: system
-  register: user_session_start
-
-- name: Enable and start Authentik pod (user scope)
+- name: Enable and start Authentik pod (system scope)
   systemd:
     name: "authentik-pod"
     enabled: "{{ authentik_service_enabled }}"
     state: "{{ authentik_service_state }}"
-    scope: user
     daemon_reload: true
-  become: true
-  become_user: "{{ authentik_user }}"
   tags: [containers, service]
 
 - name: Wait for Authentik to be ready

roles/authentik/tasks/user.yml

@@ -10,25 +10,13 @@
   user:
     name: "{{ authentik_user }}"
     group: "{{ authentik_group }}"
+    groups: "{{ [postgresql_client_group, valkey_client_group] }}"
     system: true
     shell: /bin/bash
     home: "{{ authentik_home }}"
     create_home: true
     comment: "Authentik authentication service"
-
-- name: Set up subuid for authentik user
-  lineinfile:
-    path: /etc/subuid
-    line: "{{ authentik_user }}:{{ authentik_subuid_start }}:{{ authentik_subuid_size }}"
-    create: true
-    mode: '0644'
-
-- name: Set up subgid for authentik user
-  lineinfile:
-    path: /etc/subgid
-    line: "{{ authentik_user }}:{{ authentik_subgid_start }}:{{ authentik_subgid_size }}"
-    create: true
-    mode: '0644'
+    append: true
 
 - name: Create authentik directories
   file:
@@ -39,27 +27,10 @@
     mode: '0755'
   loop:
     - "{{ authentik_home }}"
-    - "{{ authentik_home }}/.config"
-    - "{{ authentik_home }}/.config/systemd"
-    - "{{ authentik_home }}/.config/systemd/user"
-    - "{{ authentik_home }}/.config/containers"
-    - "{{ authentik_home }}/.config/containers/systemd"
     - "{{ authentik_home }}/data"
     - "{{ authentik_home }}/media"
     - "{{ authentik_home }}/logs"
 
-- name: Enable lingering for authentik user
-  command: loginctl enable-linger {{ authentik_user }}
-  args:
-    creates: "/var/lib/systemd/linger/{{ authentik_user }}"
-
-- name: Initialize user systemd for authentik
-  systemd:
-    daemon_reload: true
-    scope: user
-  become: true
-  become_user: "{{ authentik_user }}"
-
 - name: Get authentik user UID and GID for container configuration
   shell: |
     echo "uid=$(id -u {{ authentik_user }})"

roles/authentik/templates/authentik-server.container

@@ -9,12 +9,7 @@ Image={{ authentik_image }}:{{ authentik_version }}
 Pod=authentik.pod
 EnvironmentFile={{ authentik_home }}/.env
 User={{ authentik_uid }}:{{ authentik_gid }}
-Annotation=run.oci.keep_original_groups=1
-
-# Security configuration for shared memory and IPC
-Volume=/dev/shm:/dev/shm:rw
-SecurityLabelDisable=true
-AddCapability=IPC_OWNER
+PodmanArgs=--group-add {{ postgresql_client_group_gid }} --group-add {{ valkey_client_group_gid }}
 
 # Logging configuration
 LogDriver=k8s-file
@@ -34,4 +29,4 @@ Restart=always
 TimeoutStartSec=300
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target

roles/authentik/templates/authentik-worker.container

@@ -9,12 +9,7 @@ Image={{ authentik_image }}:{{ authentik_version }}
 Pod=authentik.pod
 EnvironmentFile={{ authentik_home }}/.env
 User={{ authentik_uid }}:{{ authentik_gid }}
-Annotation=run.oci.keep_original_groups=1
-
-# Security configuration for shared memory and IPC
-Volume=/dev/shm:/dev/shm:rw
-SecurityLabelDisable=true
-AddCapability=IPC_OWNER
+PodmanArgs=--group-add {{ postgresql_client_group_gid }} --group-add {{ valkey_client_group_gid }}
 
 # Logging configuration
 LogDriver=k8s-file
@@ -34,4 +29,4 @@ Restart=always
 TimeoutStartSec=300
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target

roles/authentik/templates/authentik.pod

@@ -4,11 +4,10 @@ Description=Authentik Authentication Pod
 [Pod]
 PublishPort=0.0.0.0:{{ authentik_http_port }}:{{ authentik_http_port }}
 ShmSize=256m
-PodmanArgs=
 
 [Service]
 Restart=always
 TimeoutStartSec=900
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target