Merge PR theforeman#501: Podman quadlet .image file support

Author: bochi

docs/developer/deployment.md

@@ -52,23 +52,85 @@ 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 Precedence
+
+During `foremanctl deploy`, foremanctl resolves which `.image` files to place in `/etc/containers/systemd/` using a three-tier precedence model:
+
+1. **Admin overrides** (`/etc/foremanctl/images.d/`) — highest priority. Place custom `.image` files here to override any default.
+2. **Vendor/RPM overrides** (`/usr/share/foremanctl/images.d/`) — used by packaging or vendor layers to set image sources via RPM.
+3. **Generated defaults** — built from the image variables in `images.yml` during deploy.
+
+This follows the standard Linux filesystem hierarchy: `/etc/` is for admin-controlled configuration, `/usr/share/` is for vendor-provided data that users should not edit.
+
+#### Use Cases
+
+**Upstream default (no user action):** No `.image` files exist in `/usr/share/foremanctl/images.d/` or `/etc/foremanctl/images.d/`. foremanctl generates default `.image` files from its built-in `images.yml`:
+
+```ini
+# /etc/containers/systemd/foreman.image (generated by foremanctl)
+[Image]
+Image=quay.io/foreman/foreman:nightly
+```
 
-1. **Login to your registry** using Podman and save credentials to the default auth file location:
+**RPM-provided image definitions (no user action):** An RPM installs pre-rendered `.image` files to the vendor directory (`/usr/share/foremanctl/images.d/foreman.image`, etc.). foremanctl copies them to `/etc/containers/systemd/` during deploy. The RPM's presence is the configuration:
+
+```ini
+# /usr/share/foremanctl/images.d/foreman.image
+[Image]
+Image=registry.example.com/org/foreman:6.17
+AuthFile=/etc/foreman/registry-auth.json
+```
+
+**User's own registry (user-configured):** The user creates `.image` files in `/etc/foremanctl/images.d/` pointing at their own registry (e.g., Foreman+Katello/Pulp). These override any vendor-provided files:
+
+```ini
+# /etc/foremanctl/images.d/foreman.image
+[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 `.image` file in `/etc/foremanctl/images.d/` to test a specific image build:
+
+```ini
+# /etc/foremanctl/images.d/foreman.image
+[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 only affects generated defaults (tier 3). Admin and vendor `.image` files manage their own `AuthFile=` directives.
 
 ## Deployer Stages
 
@@ -81,7 +143,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 +165,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.
+
+Admin overrides in `/etc/foremanctl/images.d/` take precedence over `images.yml` values — if an admin-provided `.image` file 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

src/roles/foreman_proxy/tasks/image.yaml

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