feat(role): expose publishing.externalIPs and tenant-root ingress via role variables (#30)

lexfrei · web-flow · commit 50b21c17a5ae · 2026-04-15T16:56:34.000+03:00
* feat(role): add cozystack_external_ips for publishing.externalIPs

Add a new list variable cozystack_external_ips that renders into
publishing.externalIPs in the Platform Package template. Required on
platforms without a native load balancer (cloud VMs, bare metal)
running the isp-full-generic variant.

Includes IP validation via the existing is_ip_address Jinja2 test,
a dedicated validate-external-ips.yml task file, and a fix for
existing tests to define the new variable in pre_tasks.

Assisted-By: Claude &lt;noreply@anthropic.com&gt;
Signed-off-by: Aleksei Sviridkin &lt;f@lex.la&gt;

* feat(role): add cozystack_tenant_root_ingress for root tenant ingress

Add a boolean variable cozystack_tenant_root_ingress (default false)
that patches the root Tenant CR to set spec.ingress=true after the
Platform Package is applied. This creates the tenant-root IngressClass
and deploys the ingress-nginx controller pods.

Waits for the root Tenant to exist (retries with backoff) since
Platform Package triggers tenant creation asynchronously.

Assisted-By: Claude &lt;noreply@anthropic.com&gt;
Signed-off-by: Aleksei Sviridkin &lt;f@lex.la&gt;

* test: add external IPs validation and rendering tests

Add test playbook that verifies externalIPs renders correctly in the
Platform Package template when IPs are provided and is omitted when
the list is empty. Add test inventories for valid and invalid IP
inputs and a CI workflow job that runs both.

Assisted-By: Claude &lt;noreply@anthropic.com&gt;
Signed-off-by: Aleksei Sviridkin &lt;f@lex.la&gt;

* docs: document external IPs and tenant ingress variables

Add cozystack_external_ips and cozystack_tenant_root_ingress to the
README optional variables table, CHANGELOG Unreleased section, and
all three example inventories (commented out).

Assisted-By: Claude &lt;noreply@anthropic.com&gt;
Signed-off-by: Aleksei Sviridkin &lt;f@lex.la&gt;

---------

Signed-off-by: Aleksei Sviridkin &lt;f@lex.la&gt;
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -129,6 +129,52 @@ jobs:
 
           echo "OK: Hostname host keys correctly rejected"
 
+  external-ips:
+    name: External IPs validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install Ansible
+        run: pip install ansible-core
+
+      - name: Build and install collection
+        run: |
+          ansible-galaxy collection build
+          ansible-galaxy collection install cozystack-installer-*.tar.gz --force
+
+      - name: Test external IPs rendering
+        run: >-
+          ansible-playbook tests/test-external-ips.yml
+          --inventory tests/test-external-ips-inventory.yml
+
+      - name: Test invalid IPs are rejected
+        run: |
+          set +e
+          output="$(ansible-playbook tests/test-external-ips.yml \
+            --inventory tests/test-invalid-ips-inventory.yml 2>&1)"
+          status=$?
+          set -e
+
+          if [ "$status" -eq 0 ]; then
+            echo "ERROR: Expected failure for invalid IPs, but playbook succeeded"
+            exit 1
+          fi
+
+          if ! grep -q "not a valid IP address in cozystack_external_ips" <<< "$output"; then
+            echo "ERROR: Playbook failed, but not due to IP validation"
+            echo "$output"
+            exit 1
+          fi
+
+          echo "OK: Invalid IPs correctly rejected"
+
   e2e:
     name: E2E
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -38,6 +38,15 @@ Synced with Cozystack v1.1.3.
 Unreleased
 ==========
 
+- New variable ``cozystack_external_ips`` (list, default ``[]``): external
+  IP addresses for ingress-nginx Service ``externalIPs``. Required on
+  ``isp-full-generic`` platform variant when nodes lack a native load
+  balancer (cloud VMs, bare metal).
+- New variable ``cozystack_tenant_root_ingress`` (bool, default ``false``):
+  when enabled, patches the root Tenant CR to set ``spec.ingress: true``
+  after Platform Package apply, creating the ``tenant-root`` IngressClass
+  and ingress-nginx controller pods.
+
 Node prerequisites: comprehensive audit and install in examples.
 
 - Example prepare playbooks now install the full set of node prerequisites.
diff --git a/README.md b/README.md
@@ -322,6 +322,8 @@ Runs on `server[0]` only.
 | `cozystack_create_platform_package` | `true` | Create Platform Package CR after install |
 | `cozystack_platform_variant` | `isp-full-generic` | Platform variant: default, isp-full, isp-hosted, isp-full-generic |
 | `cozystack_root_host` | `""` | Domain for Cozystack services (empty = skip publishing) |
+| `cozystack_external_ips` | `[]` | List of external IPs for ingress-nginx Service. Required on platforms without a native LB (cloud VMs, bare metal). Each entry must be a valid IPv4/IPv6 address. |
+| `cozystack_tenant_root_ingress` | `false` | Enable ingress on the root tenant. When `true`, patches the root Tenant CR after Platform Package apply to create IngressClass and ingress-nginx controller. |
 | `cozystack_pod_cidr` | `10.42.0.0/16` | Pod CIDR for Platform Package |
 | `cozystack_pod_gateway` | `10.42.0.1` | Pod gateway |
 | `cozystack_svc_cidr` | `10.43.0.0/16` | Service CIDR |
diff --git a/examples/rhel/inventory.yml b/examples/rhel/inventory.yml
@@ -31,6 +31,13 @@ cluster:
     cozystack_root_host: "cozy.example.com"
     cozystack_platform_variant: "isp-full-generic"
 
+    # External IPs for ingress-nginx (required on cloud VMs without native LB)
+    # cozystack_external_ips:
+    #   - "203.0.113.10"
+
+    # Enable ingress on root tenant (creates IngressClass + controller)
+    # cozystack_tenant_root_ingress: true
+
     # Extra k3s flags (used in prepare-rhel.yml)
     cozystack_k3s_extra_args: "--tls-san=203.0.113.10"
 
diff --git a/examples/suse/inventory.yml b/examples/suse/inventory.yml
@@ -31,6 +31,13 @@ cluster:
     cozystack_root_host: "cozy.example.com"
     cozystack_platform_variant: "isp-full-generic"
 
+    # External IPs for ingress-nginx (required on cloud VMs without native LB)
+    # cozystack_external_ips:
+    #   - "203.0.113.10"
+
+    # Enable ingress on root tenant (creates IngressClass + controller)
+    # cozystack_tenant_root_ingress: true
+
     # Extra k3s flags (used in prepare-suse.yml)
     cozystack_k3s_extra_args: "--tls-san=203.0.113.10"
 
diff --git a/examples/ubuntu/inventory.yml b/examples/ubuntu/inventory.yml
@@ -38,6 +38,13 @@ cluster:
     cozystack_root_host: "cozy.example.com"
     cozystack_platform_variant: "isp-full-generic"
 
+    # External IPs for ingress-nginx (required on cloud VMs without native LB)
+    # cozystack_external_ips:
+    #   - "203.0.113.10"
+
+    # Enable ingress on root tenant (creates IngressClass + controller)
+    # cozystack_tenant_root_ingress: true
+
     # Extra k3s flags (used in prepare-ubuntu.yml)
     cozystack_k3s_extra_args: "--tls-san=203.0.113.10"
 
diff --git a/roles/cozystack/defaults/main.yml b/roles/cozystack/defaults/main.yml
@@ -53,6 +53,16 @@ cozystack_platform_variant: "isp-full-generic"
 # Leave empty to skip publishing config in the Platform Package
 cozystack_root_host: ""
 
+# External IPs for ingress-nginx Service (type: LoadBalancer).
+# Required on platforms without a native LB (cloud VMs, bare metal).
+# Each entry must be a valid IPv4 or IPv6 address.
+cozystack_external_ips: []
+
+# Enable ingress on the root tenant (tenant-root).
+# When true, patches the root Tenant CR after Platform Package apply
+# so that IngressClass and ingress-nginx controller are created.
+cozystack_tenant_root_ingress: false
+
 # Comma-separated control-plane node IPs for kube-ovn RAFT consensus.
 # Empty = auto-detect from 'server' inventory group host keys.
 cozystack_master_nodes: ""
diff --git a/roles/cozystack/tasks/main.yml b/roles/cozystack/tasks/main.yml
@@ -13,6 +13,12 @@
   ansible.builtin.include_tasks: compute-master-nodes.yml
   when: cozystack_create_platform_package
 
+- name: Validate external IP addresses
+  ansible.builtin.include_tasks: validate-external-ips.yml
+  when:
+    - cozystack_create_platform_package
+    - cozystack_external_ips | length > 0
+
 - name: Set architecture for Helm download
   ansible.builtin.set_fact:
     _cozystack_arch: "{{ 'amd64' if ansible_architecture == 'x86_64' else 'arm64' }}"
@@ -147,3 +153,38 @@
   become: true
   changed_when: false
   when: cozystack_create_platform_package
+
+- name: Wait for root Tenant to exist
+  ansible.builtin.command:
+    cmd: >-
+      kubectl --kubeconfig {{ cozystack_kubeconfig }}
+      wait tenants.apps.cozystack.io/root
+      --namespace tenant-root
+      --for=jsonpath='{.metadata.name}'=root
+      --timeout={{ cozystack_operator_wait_timeout }}s
+  become: true
+  changed_when: false
+  register: _tenant_wait
+  retries: 5
+  delay: 15
+  until: _tenant_wait.rc == 0
+  when:
+    - cozystack_tenant_root_ingress
+    - cozystack_create_platform_package
+    - not ansible_check_mode
+
+- name: Enable ingress on root Tenant
+  ansible.builtin.command:
+    cmd: >-
+      kubectl --kubeconfig {{ cozystack_kubeconfig }}
+      patch tenants.apps.cozystack.io root
+      --namespace tenant-root
+      --type=merge
+      --patch '{"spec":{"ingress":true}}'
+  become: true
+  register: _tenant_patch
+  changed_when: "'patched' in _tenant_patch.stdout and '(no change)' not in _tenant_patch.stdout"
+  when:
+    - cozystack_tenant_root_ingress
+    - cozystack_create_platform_package
+    - not ansible_check_mode
diff --git a/roles/cozystack/tasks/validate-external-ips.yml b/roles/cozystack/tasks/validate-external-ips.yml
@@ -0,0 +1,22 @@
+---
+# Validate that each entry in cozystack_external_ips is a valid IP address.
+# Included from main.yml and tests.
+- name: Validate cozystack_external_ips is a list
+  ansible.builtin.assert:
+    that:
+      - cozystack_external_ips is sequence
+      - cozystack_external_ips is not string
+      - cozystack_external_ips is not mapping
+    fail_msg: >-
+      cozystack_external_ips must be a list of IP address strings.
+      Got type {{ cozystack_external_ips | type_debug }}.
+
+- name: Validate each external IP is a valid address
+  ansible.builtin.assert:
+    that:
+      - item is cozystack.installer.is_ip_address
+    fail_msg: >-
+      '{{ item }}' is not a valid IP address in cozystack_external_ips.
+      Each entry must be a valid IPv4 or IPv6 address.
+  loop: "{{ cozystack_external_ips }}"
+  when: cozystack_external_ips | length > 0
diff --git a/roles/cozystack/templates/platform-package.yml.j2 b/roles/cozystack/templates/platform-package.yml.j2
@@ -28,4 +28,7 @@ spec:
         publishing:
           host: {{ cozystack_root_host | to_json }}
           apiServerEndpoint: {{ _cozystack_api_endpoint | to_json }}
+{% if cozystack_external_ips | length > 0 %}
+          externalIPs: {{ cozystack_external_ips | to_json }}
+{% endif %}
 {% endif %}
diff --git a/tests/test-external-ips-inventory.yml b/tests/test-external-ips-inventory.yml
@@ -0,0 +1,20 @@
+---
+# Test inventory with external IPs and root host set.
+# Used to verify externalIPs rendering in the Platform Package template.
+cluster:
+  children:
+    server:
+      hosts:
+        10.0.0.10:
+          ansible_connection: local
+          ansible_host: 127.0.0.1
+    agent:
+      hosts: {}
+
+  vars:
+    ansible_user: runner
+    cozystack_api_server_host: "10.0.0.10"
+    cozystack_root_host: "cozy.example.com"
+    cozystack_external_ips:
+      - "203.0.113.10"
+      - "203.0.113.11"
diff --git a/tests/test-external-ips.yml b/tests/test-external-ips.yml
@@ -0,0 +1,118 @@
+---
+# Verify that cozystack_external_ips renders correctly in the Platform Package
+# template and that IP validation rejects invalid entries.
+- name: Test external IPs rendering in Platform Package template
+  hosts: server[0]
+  gather_facts: false
+  pre_tasks:
+    - name: Set template defaults when not defined by inventory
+      ansible.builtin.set_fact:
+        cozystack_master_nodes: "{{ cozystack_master_nodes | default('') }}"
+        cozystack_api_server_host: "{{ cozystack_api_server_host | default('127.0.0.1') }}"
+        cozystack_api_server_port: "{{ cozystack_api_server_port | default('6443') }}"
+        cozystack_namespace: "{{ cozystack_namespace | default('cozy-system') }}"
+        cozystack_platform_variant: "{{ cozystack_platform_variant | default('isp-full-generic') }}"
+        cozystack_root_host: "{{ cozystack_root_host | default('') }}"
+        cozystack_external_ips: "{{ cozystack_external_ips | default([]) }}"
+        cozystack_pod_cidr: "{{ cozystack_pod_cidr | default('10.42.0.0/16') }}"
+        cozystack_pod_gateway: "{{ cozystack_pod_gateway | default('10.42.0.1') }}"
+        cozystack_svc_cidr: "{{ cozystack_svc_cidr | default('10.43.0.0/16') }}"
+        cozystack_join_cidr: "{{ cozystack_join_cidr | default('100.64.0.0/16') }}"
+  tasks:
+    - name: Include role master-node computation
+      ansible.builtin.include_tasks:
+        file: "{{ playbook_dir }}/../roles/cozystack/tasks/compute-master-nodes.yml"
+
+    - name: Include external IP validation
+      ansible.builtin.include_tasks:
+        file: "{{ playbook_dir }}/../roles/cozystack/tasks/validate-external-ips.yml"
+      when: cozystack_external_ips | length > 0
+
+    - name: Construct API server endpoint
+      ansible.builtin.set_fact:
+        _cozystack_api_endpoint: "https://{{ cozystack_api_server_host }}:{{ cozystack_api_server_port }}"
+
+    - name: Render Platform Package template
+      ansible.builtin.template:
+        src: "{{ playbook_dir }}/../roles/cozystack/templates/platform-package.yml.j2"
+        dest: /tmp/cozystack-test-external-ips.yml
+        mode: "0600"
+
+    - name: Read rendered manifest
+      ansible.builtin.slurp:
+        src: /tmp/cozystack-test-external-ips.yml
+      register: _rendered_manifest
+
+    - name: Assert externalIPs is present when external IPs are set
+      ansible.builtin.assert:
+        that:
+          - "'externalIPs' in _rendered_content"
+          - "(cozystack_external_ips | to_json) in _rendered_content"
+        fail_msg: >-
+          Rendered template does not contain expected externalIPs.
+          Expected {{ cozystack_external_ips | to_json }} in output.
+      vars:
+        _rendered_content: "{{ _rendered_manifest.content | b64decode }}"
+      when: cozystack_external_ips | length > 0
+
+    - name: Show rendered template (debug)
+      ansible.builtin.debug:
+        msg: "{{ _rendered_manifest.content | b64decode }}"
+
+    - name: Clean up test manifest
+      ansible.builtin.file:
+        path: /tmp/cozystack-test-external-ips.yml
+        state: absent
+      changed_when: false
+
+- name: Test empty external IPs omits externalIPs from template
+  hosts: server[0]
+  gather_facts: false
+  pre_tasks:
+    - name: Set defaults with empty external IPs
+      ansible.builtin.set_fact:
+        cozystack_master_nodes: "{{ cozystack_master_nodes | default('') }}"
+        cozystack_api_server_host: "{{ cozystack_api_server_host | default('127.0.0.1') }}"
+        cozystack_api_server_port: "{{ cozystack_api_server_port | default('6443') }}"
+        cozystack_namespace: "{{ cozystack_namespace | default('cozy-system') }}"
+        cozystack_platform_variant: "{{ cozystack_platform_variant | default('isp-full-generic') }}"
+        cozystack_root_host: "cozy.example.com"
+        cozystack_external_ips: []
+        cozystack_pod_cidr: "{{ cozystack_pod_cidr | default('10.42.0.0/16') }}"
+        cozystack_pod_gateway: "{{ cozystack_pod_gateway | default('10.42.0.1') }}"
+        cozystack_svc_cidr: "{{ cozystack_svc_cidr | default('10.43.0.0/16') }}"
+        cozystack_join_cidr: "{{ cozystack_join_cidr | default('100.64.0.0/16') }}"
+  tasks:
+    - name: Include role master-node computation
+      ansible.builtin.include_tasks:
+        file: "{{ playbook_dir }}/../roles/cozystack/tasks/compute-master-nodes.yml"
+
+    - name: Construct API server endpoint
+      ansible.builtin.set_fact:
+        _cozystack_api_endpoint: "https://{{ cozystack_api_server_host }}:{{ cozystack_api_server_port }}"
+
+    - name: Render Platform Package template
+      ansible.builtin.template:
+        src: "{{ playbook_dir }}/../roles/cozystack/templates/platform-package.yml.j2"
+        dest: /tmp/cozystack-test-external-ips-empty.yml
+        mode: "0600"
+
+    - name: Read rendered manifest
+      ansible.builtin.slurp:
+        src: /tmp/cozystack-test-external-ips-empty.yml
+      register: _rendered_manifest_empty
+
+    - name: Assert externalIPs is NOT present when list is empty
+      ansible.builtin.assert:
+        that:
+          - "'externalIPs' not in _rendered_content"
+        fail_msg: >-
+          Rendered template should NOT contain externalIPs when list is empty.
+      vars:
+        _rendered_content: "{{ _rendered_manifest_empty.content | b64decode }}"
+
+    - name: Clean up test manifest
+      ansible.builtin.file:
+        path: /tmp/cozystack-test-external-ips-empty.yml
+        state: absent
+      changed_when: false
diff --git a/tests/test-invalid-ips-inventory.yml b/tests/test-invalid-ips-inventory.yml
@@ -0,0 +1,19 @@
+---
+# Inventory with invalid entries in cozystack_external_ips.
+# Used to verify that IP validation rejects non-IP strings.
+cluster:
+  children:
+    server:
+      hosts:
+        10.0.0.10:
+          ansible_connection: local
+          ansible_host: 127.0.0.1
+    agent:
+      hosts: {}
+
+  vars:
+    ansible_user: runner
+    cozystack_api_server_host: "10.0.0.10"
+    cozystack_root_host: "cozy.example.com"
+    cozystack_external_ips:
+      - "not-an-ip"
diff --git a/tests/test-master-nodes.yml b/tests/test-master-nodes.yml
@@ -14,6 +14,7 @@
         cozystack_namespace: "{{ cozystack_namespace | default('cozy-system') }}"
         cozystack_platform_variant: "{{ cozystack_platform_variant | default('isp-full-generic') }}"
         cozystack_root_host: "{{ cozystack_root_host | default('') }}"
+        cozystack_external_ips: "{{ cozystack_external_ips | default([]) }}"
         cozystack_pod_cidr: "{{ cozystack_pod_cidr | default('10.42.0.0/16') }}"
         cozystack_pod_gateway: "{{ cozystack_pod_gateway | default('10.42.0.1') }}"
         cozystack_svc_cidr: "{{ cozystack_svc_cidr | default('10.43.0.0/16') }}"
