fix(dependencies): address PR review findings

- Read the MetalLB speaker tag check from the managed host with slurp
  instead of a controller-side file lookup, and match the full image
  reference
- Restore the tigera-operator namespace on the Calico operator Deployment
  wait while keeping the managed CRD waits cluster-scoped
- Make Molecule verify inputs durable and scenario-specific via a
  per-scenario verify-vars.yml, driven by explicit verify_cni/verify_lb
  values instead of non-persisted converge facts
- Rename the kube-vip multi-peer BGP env var from bgppeers to bgp_peers
  and vip_cidr to vip_subnet so v1.2.2 actually reads them
- Map the legacy Cilium routed mode to tunnel and stop passing the alias
  directly to the chart
- Use return-code based failed_when on apply and preflight commands so
  non-error failures are no longer treated as success
- Clarify the sequential K3s upgrade path and backups in the README
- Add kube-vip and MetalLB regression tests and a Cilium mode mapping unit

roles/k3s_server/tasks/metallb.yml

@@ -29,19 +29,26 @@
     label: "{{ item.change }} => {{ item.to }}"
   when: ansible_hostname == hostvars[groups[group_name_master | default('master')][0]]['ansible_hostname']
 
-- name: Read back MetalLB manifest to verify the speaker image tag
+- name: Read back MetalLB manifest from first master
+  ansible.builtin.slurp:
+    src: /var/lib/rancher/k3s/server/manifests/metallb-crds.yaml
+  register: metallb_manifest
+  when: ansible_hostname == hostvars[groups[group_name_master | default('master')][0]]['ansible_hostname']
+
+- name: Check the MetalLB speaker image reference is present
   ansible.builtin.set_fact:
     metallb_manifest_has_speaker_tag: >-
       {{
-        metal_lb_speaker_tag_version in
-        lookup('ansible.builtin.file', '/var/lib/rancher/k3s/server/manifests/metallb-crds.yaml')
+        ('quay.io/metallb/speaker:' ~ metal_lb_speaker_tag_version) in
+        (metallb_manifest.content | default('') | b64decode)
       }}
   when: ansible_hostname == hostvars[groups[group_name_master | default('master')][0]]['ansible_hostname']
 
 - name: Fail if MetalLB speaker tag was not applied to the manifest
   ansible.builtin.fail:
     msg: >-
-      MetalLB speaker image tag {{ metal_lb_speaker_tag_version }}
+      MetalLB speaker image reference
+      quay.io/metallb/speaker:{{ metal_lb_speaker_tag_version }}
       was not found in the downloaded manifest. The upstream image
       reference may have changed.
   when:

roles/k3s_server/templates/vip.yaml.j2

@@ -36,7 +36,7 @@ spec:
         - name: vip_interface
           value: {{ kube_vip_iface }}
 {% endif %}
-        - name: vip_cidr
+        - name: vip_subnet
           value: "{{ apiserver_endpoint | ansible.utils.ipsubnet | ansible.utils.ipaddr('prefix') }}"
         - name: cp_enable
           value: "true"
@@ -62,7 +62,7 @@ spec:
           value: "{{ kube_vip_bgp_routerid }}"
 {% endif %}
 {% if _kube_vip_bgp_peers | length > 0 %}
-        - name: bgppeers
+        - name: bgp_peers
           value: "{{ _kube_vip_bgp_peers | map(attribute='peer_address') | zip(_kube_vip_bgp_peers | map(attribute='peer_asn')) | map('join', ':') | join(',') }}"  # yamllint disable-line rule:line-length
 {% else %}
 {% if kube_vip_bgp_as is defined %}

roles/k3s_server_post/meta/main.yml

@@ -93,10 +93,14 @@ argument_specs:
         default: ~
 
       cilium_mode:
-        description: Inner-node communication mode
+        description:
+          - Inner-node communication mode.
+          - Cilium accepts `native` or `tunnel`. `routed` is accepted as a
+            legacy alias and is mapped to `tunnel` at install time.
         default: native
         choices:
           - native
+          - tunnel
           - routed
 
       cilium_tag:

roles/k3s_server_post/tasks/calico.yml

@@ -37,7 +37,7 @@
         'created' in apply_crds.stdout or
         'configured' in apply_crds.stdout or
         'applied' in apply_crds.stdout
-      failed_when: "'Error' in apply_crds.stderr"
+      failed_when: apply_crds.rc != 0
 
     - name: Apply Tigera Operator manifest idempotently with server-side apply
       ansible.builtin.command: >-
@@ -49,11 +49,12 @@
         'created' in apply_operator.stdout or
         'configured' in apply_operator.stdout or
         'applied' in apply_operator.stdout
-      failed_when: "'Error' in apply_operator.stderr"
+      failed_when: apply_operator.rc != 0
 
     - name: Wait for Tigera Operator and managed CRDs to become available
       ansible.builtin.command: >-
         {{ k3s_kubectl_binary | default('k3s kubectl') }} wait {{ item.type }}/{{ item.name }}
+        {% if item.namespace is defined %}--namespace='{{ item.namespace }}'{% endif %}
         --for=condition={{ item.condition }}
         --timeout=30s
       register: tigera_result
@@ -62,7 +63,7 @@
       retries: 7
       delay: 7
       with_items:
-        - { name: tigera-operator, type: deployment, condition: Available=True }
+        - { name: tigera-operator, type: deployment, namespace: tigera-operator, condition: Available=True }
         - { name: installations.operator.tigera.io, type: crd, condition: Established }
         - { name: apiservers.operator.tigera.io, type: crd, condition: Established }
       loop_control:
@@ -85,7 +86,7 @@
         'configured' in apply_cr.stdout or
         'created' in apply_cr.stdout or
         'unchanged' in apply_cr.stdout
-      failed_when: "'Error' in apply_cr.stderr"
+      failed_when: apply_cr.rc != 0
 
     - name: Wait for Calico system resources to be available
       ansible.builtin.command: >-

roles/k3s_server_post/tasks/cilium.yml

@@ -143,6 +143,13 @@
               Target Cilium version: {{ cilium_tag }},
               Update needed: {{ cilium_needs_update }}
 
+    - name: Map the legacy routed mode to Cilium tunnel mode
+      ansible.builtin.set_fact:
+        # Cilium 1.20 accepts `native` or `tunnel`. `routed` was the name used
+        # by older releases and is kept only as a backward-compatible alias.
+        cilium_routing_mode: >-
+          {{ 'tunnel' if cilium_mode == 'routed' else cilium_mode }}
+
     - name: Install Cilium
       ansible.builtin.command: >-
         {% if cilium_installed.rc != 0 %}
@@ -154,13 +161,13 @@
         --helm-set operator.replicas="1"
         {{ '--helm-set devices=' + cilium_iface if cilium_iface != 'auto' else '' }}
         --helm-set ipam.operator.clusterPoolIPv4PodCIDRList={{ cluster_cidr }}
-        {% if cilium_mode == "native" or (cilium_bgp and cilium_exportPodCIDR != 'false') %}
+        {% if cilium_routing_mode == "native" or (cilium_bgp and cilium_exportPodCIDR != 'false') %}
         --helm-set ipv4NativeRoutingCIDR={{ cluster_cidr }}
         {% endif %}
         --helm-set k8sServiceHost="127.0.0.1"
         --helm-set k8sServicePort="6444"
-        --helm-set routingMode={{ cilium_mode }}
-        --helm-set autoDirectNodeRoutes={{ "true" if cilium_mode == "native" else "false" }}
+        --helm-set routingMode={{ cilium_routing_mode }}
+        --helm-set autoDirectNodeRoutes={{ "true" if cilium_routing_mode == "native" else "false" }}
         --helm-set kubeProxyReplacement={{ kube_proxy_replacement }}
         --helm-set bpf.masquerade={{ enable_bpf_masquerade }}
         --helm-set bgpControlPlane.enabled={{ cilium_bgp | default("false") }}
@@ -236,7 +243,7 @@
             apply --dry-run=server -f /tmp/k3s/cilium-bgp.yaml
           register: preflight_cr
           changed_when: false
-          failed_when: "'error' in preflight_cr.stderr | lower"
+          failed_when: preflight_cr.rc != 0
 
         - name: Apply BGP manifests
           ansible.builtin.command: >-
@@ -244,7 +251,7 @@
             apply -f /tmp/k3s/cilium-bgp.yaml
           register: apply_cr
           changed_when: "'configured' in apply_cr.stdout or 'created' in apply_cr.stdout"
-          failed_when: "'is invalid' in apply_cr.stderr"
+          failed_when: apply_cr.rc != 0
 
         - name: Remove deprecated CiliumBGPPeeringPolicy after v2 resources are accepted
           ansible.builtin.command: >-
@@ -252,8 +259,9 @@
             delete CiliumBGPPeeringPolicy.cilium.io 01-bgp-peering-policy
           register: delete_old_policy
           changed_when: "'deleted' in delete_old_policy.stdout"
+          # The policy (and possibly its CRD) may already be absent; this is
+          # intentionally tolerated, not a command whose failure must be hidden.
           failed_when: false
-          ignore_errors: true
 
         - name: Test for BGP config resources
           ansible.builtin.command: "{{ item }}"