Add Podman quadlet .image file support

Introduce .image quadlet units to decouple image sourcing from container
definitions. Container roles now reference Image=<name>.image instead of
full registry URLs, and a new images role handles deployment with a
three-tier precedence model: admin overrides (/etc/foremanctl/images.d/)
> vendor RPMs (/usr/share/foremanctl/images.d/) > generated defaults.

Resolves: #277

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ehelms

.github/workflows/test.yml

@@ -119,7 +119,7 @@ jobs:
           vagrant ssh quadlet -- sudo systemctl restart fapolicyd
       - name: Run image pull
         run: |
-          ./foremanctl pull-images
+          ./foremanctl pull-images ${{ matrix.database == 'external' && '--database-mode=external' || '' }}
       - name: Run deployment
         run: |
           ./foremanctl deploy \

docs/developer/deployment.md

@@ -52,23 +52,84 @@ IOP (Insights Operating Platform) deploys on-premise Insights services for advis
 
 See [IOP Architecture](iop.md) for details on the services deployed and configuration options.
 
-### Authenticated Registry Handling
+### Image Management
 
-If you need to pull images from private or authenticated container registries, you can configure registry authentication using Podman's auth file.
+foremanctl uses Podman quadlet `.image` units to separate image sourcing from container definitions. Each unique container image (foreman, candlepin, pulp, etc.) gets a corresponding `.image` file deployed to `/etc/containers/systemd/`. Container roles reference these by name rather than by full image URL:
 
-#### Setting up Registry Authentication
+```ini
+# /etc/containers/systemd/foreman.image
+[Image]
+Image=quay.io/foreman/foreman:nightly
+```
+
+```ini
+# /etc/containers/systemd/foreman.container (excerpt)
+[Container]
+Image=foreman.image
+```
+
+All containers that share a base image (e.g., foreman, dynflow-sidekiq, foreman-recurring) reference the same `.image` unit. systemd ensures the image is pulled before any dependent container starts.
+
+#### Image Overrides via Drop-ins
+
+foremanctl uses quadlet's native drop-in mechanism for image overrides. Each `.image` file can have a corresponding `.image.d/` directory containing numbered drop-in configuration files. Drop-ins are applied in lexicographic order (last wins):
+
+```
+/etc/containers/systemd/
+  foreman.image                        # base, always templated by foremanctl
+  foreman.image.d/
+    90-user.conf                       # optional: user override
+```
+
+Precedence (last wins):
+
+1. `foreman.image` — foremanctl default from `images.yml`
+2. `90-user.conf` — user-provided layer (not managed by foremanctl)
+
+Numbered prefixes enforce ordering with gaps for future layers.
+
+#### Use Cases
 
-1. **Login to your registry** using Podman and save credentials to the default auth file location:
+**Upstream default (no user action):** foremanctl generates `.image` files from its built-in `images.yml`:
+
+```ini
+# /etc/containers/systemd/foreman.image (generated by foremanctl)
+[Image]
+Image=quay.io/foreman/foreman:nightly
+```
+
+**User's own registry:** The user creates a `90-user.conf` drop-in to point at their own registry. This overrides the base layer:
+
+```ini
+# /etc/containers/systemd/foreman.image.d/90-user.conf
+[Image]
+Image=katello.example.com/Default_Organization/foreman:6.17
+AuthFile=/etc/foreman/registry-auth.json
+```
+
+**Developer testing a container build:** The developer creates a `90-user.conf` drop-in to test a specific image build:
+
+```ini
+# /etc/containers/systemd/foreman.image.d/90-user.conf
+[Image]
+Image=quay.io/foreman/foreman:pr-12345
+```
+
+#### Authenticated Registry Handling
+
+If you need to pull images from private or authenticated container registries:
+
+1. **Login to your registry** using Podman and save credentials to an auth file:
 ```bash
 podman login <registry> --authfile=/etc/foreman/registry-auth.json
 ```
 
-2. **Deploy as usual** - foremanctl will automatically detect and use the authentication file:
+2. **Set the global auth file** so all generated `.image` units include it:
 ```bash
-./foremanctl deploy
+./foremanctl deploy --registry-auth-file=/etc/foreman/registry-auth.json
 ```
 
-This approach integrates seamlessly with both the happy path and advanced deployment paths described above. The authentication is handled transparently during image pulling operations.
+This affects the base `.image` files. Drop-in overrides (disconnected or user) manage their own `AuthFile=` directives independently.
 
 ## Deployer Stages
 
@@ -81,7 +142,7 @@ Some of the stages will be made available to the user to run independently.
     a. system requirements
     b. tuning requirements
     c. certificate requirements
-  4. Place `.container` files
+  4. Place `.image` and `.container` files
   5. Create podman secrets
   6. Reload systemd
   7. (re)start services
@@ -103,7 +164,9 @@ When the user provides parameters to alter the deployment, the deployment utilit
 
 ## Container changes (Upgrades)
 
-When the running containers change because the stream was changed in the configuration, the deployment utility will pull the new images and use the new images when starting services.
+When the running containers change because the stream was changed in the configuration, the deployment utility regenerates `.image` units with the new image references and restarts services to pull and use the updated images.
+
+User drop-in overrides in `.image.d/90-user.conf` take precedence over the base `.image` values — if a user-provided drop-in pins a specific tag, it will not be changed by an upgrade.
 
 As there is currently no way for the deployment utility to verify which image version is used by a running service, the user is advised to stop all services before performing an upgrade.
 

src/playbooks/pull-images/pull-images.yaml

@@ -11,27 +11,49 @@
   roles:
     - role: pre_install
   post_tasks:
-    - name: Pull an image
-      containers.podman.podman_image:
+    - name: Deploy core image units
+      ansible.builtin.include_role:
         name: "{{ item }}"
-      environment:
-        REGISTRY_AUTH_FILE: "{{ registry_auth_file }}"
-      loop: "{{ images }}"
+        tasks_from: image.yaml
+      loop:
+        - foreman
+        - candlepin
+        - pulp
+        - redis
 
-    - name: Pull foreman_proxy images
-      containers.podman.podman_image:
-        name: "{{ item }}"
-      environment:
-        REGISTRY_AUTH_FILE: "{{ registry_auth_file }}"
-      loop: "{{ foreman_proxy_images }}"
-      when:
-        - "'foreman-proxy' in enabled_features"
+    - name: Deploy database image units
+      ansible.builtin.include_role:
+        name: postgresql
+        tasks_from: image.yaml
+      when: database_mode == 'internal'
+
+    - name: Deploy proxy image units
+      ansible.builtin.include_role:
+        name: foreman_proxy
+        tasks_from: image.yaml
+      when: "'foreman-proxy' in enabled_features"
 
-    - name: Pull database images
-      containers.podman.podman_image:
+    - name: Deploy IOP image units
+      ansible.builtin.include_role:
         name: "{{ item }}"
-      environment:
-        REGISTRY_AUTH_FILE: "{{ registry_auth_file }}"
-      loop: "{{ database_images }}"
-      when:
-        - database_mode == 'internal'
+        tasks_from: image.yaml
+      loop:
+        - iop_kafka
+        - iop_ingress
+        - iop_puptoo
+        - iop_yuptoo
+        - iop_engine
+        - iop_gateway
+        - iop_inventory
+        - iop_advisor
+        - iop_remediation
+        - iop_vmaas
+        - iop_vulnerability
+        - iop_advisor_frontend
+        - iop_inventory_frontend
+        - iop_vulnerability_frontend
+      when: "'iop' in enabled_features"
+
+    - name: Run daemon reload
+      ansible.builtin.systemd:
+        daemon_reload: true

src/roles/candlepin/defaults/main.yml

@@ -14,7 +14,6 @@ candlepin_ciphers:
   - TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
 candlepin_container_image: quay.io/foreman/candlepin
 candlepin_container_tag: "4.4.14"
-candlepin_registry_auth_file: /etc/foreman/registry-auth.json
 
 candlepin_database_host: localhost
 candlepin_database_port: 5432

src/roles/candlepin/tasks/image.yaml

@@ -0,0 +1,9 @@
+---
+- name: Deploy candlepin image unit
+  ansible.builtin.include_role:
+    name: images
+    tasks_from: deploy_image.yaml
+  vars:
+    images_definition:
+      name: candlepin
+      image: "{{ candlepin_container_image }}:{{ candlepin_container_tag }}"

src/roles/candlepin/tasks/main.yml

@@ -1,4 +1,7 @@
 ---
+- name: Deploy candlepin image
+  ansible.builtin.include_tasks: image.yaml
+
 - name: Create log directories
   ansible.builtin.file:
     path: "{{ item }}"
@@ -55,17 +58,10 @@
   notify:
     - Restart candlepin
 
-- name: Pull the Candlepin container image
-  containers.podman.podman_image:
-    name: "{{ candlepin_container_image }}:{{ candlepin_container_tag }}"
-    state: present
-  environment:
-    REGISTRY_AUTH_FILE: "{{ candlepin_registry_auth_file }}"
-
 - name: Deploy Candlepin quadlet
   containers.podman.podman_container:
     name: "candlepin"
-    image: "{{ candlepin_container_image }}:{{ candlepin_container_tag }}"
+    image: candlepin.image
     state: quadlet
     network: host
     hostname: "{{ ansible_facts['hostname'] }}.local"

src/roles/foreman/defaults/main.yaml

@@ -1,7 +1,6 @@
 ---
 foreman_container_image: "quay.io/foreman/foreman"
 foreman_container_tag: "nightly"
-foreman_registry_auth_file: /etc/foreman/registry-auth.json
 
 foreman_database_name: foreman
 foreman_database_user: foreman

src/roles/foreman/tasks/image.yaml

@@ -0,0 +1,9 @@
+---
+- name: Deploy foreman image unit
+  ansible.builtin.include_role:
+    name: images
+    tasks_from: deploy_image.yaml
+  vars:
+    images_definition:
+      name: foreman
+      image: "{{ foreman_container_image }}:{{ foreman_container_tag }}"

src/roles/foreman/tasks/main.yaml

@@ -1,10 +1,6 @@
 ---
-- name: Pull the Foreman container image
-  containers.podman.podman_image:
-    name: "{{ foreman_container_image }}:{{ foreman_container_tag }}"
-    state: present
-  environment:
-    REGISTRY_AUTH_FILE: "{{ foreman_registry_auth_file }}"
+- name: Deploy foreman image
+  ansible.builtin.include_tasks: image.yaml
 
 - name: Create secret for DATABASE_URL
   containers.podman.podman_secret:
@@ -98,7 +94,7 @@
 - name: Deploy Foreman Container
   containers.podman.podman_container:
     name: "foreman"
-    image: "{{ foreman_container_image }}:{{ foreman_container_tag }}"
+    image: foreman.image
     state: quadlet
     sdnotify: true
     network: host
@@ -136,7 +132,7 @@
   containers.podman.podman_container:
     name: "dynflow-sidekiq-%i"
     quadlet_filename: "dynflow-sidekiq@"
-    image: "{{ foreman_container_image }}:{{ foreman_container_tag }}"
+    image: foreman.image
     state: quadlet
     sdnotify: true
     network: host
@@ -191,7 +187,7 @@
     name: "foreman-recurring-{{ item.instance }}"
     quadlet_filename: "foreman-recurring@{{ item.instance }}"
     state: quadlet
-    image: "{{ foreman_container_image }}:{{ foreman_container_tag }}"
+    image: foreman.image
     sdnotify: false
     network: host
     hostname: "{{ ansible_facts['hostname'] }}.local"

src/roles/foreman_proxy/defaults/main.yaml

@@ -1,7 +1,6 @@
 ---
 foreman_proxy_container_image: "quay.io/foreman/foreman-proxy"
 foreman_proxy_container_tag: "nightly"
-foreman_proxy_registry_auth_file: /etc/foreman/registry-auth.json
 
 foreman_proxy_name: "{{ ansible_facts['fqdn'] }}"
 foreman_proxy_https_port: 8443