docs: pass boolean extra-vars as JSON for Ansible 12 compatibility (#13526)

* docs: pass boolean extra-vars as JSON for Ansible 12 compatibility Ansible 12 no longer accepts boolean values passed with -e var=true; the value is treated as a string, which breaks conditionals that expect a boolean. Update all documentation examples to use JSON syntax for boolean extra-vars and link to the Ansible 12 porting guide. Signed-off-by: Shashank Varma <324153016+shashankvarma499@users.noreply.github.com> * docs: clarify Ansible boolean types and configuration examples Signed-off-by: Kay Yan <kay.yan@daocloud.io> --------- Signed-off-by: Shashank Varma <324153016+shashankvarma499@users.noreply.github.com> Signed-off-by: Kay Yan <kay.yan@daocloud.io> Co-authored-by: Shashank Varma <324153016+shashankvarma499@users.noreply.github.com> Co-authored-by: Kay Yan <kay.yan@daocloud.io>
2026-10-29 22:03:22 -02:30 · 2026-09-20 06:05:59 +00:00
parent b8ad8289a8
commit 2af9b1cc94
6 changed files with 17 additions and 18 deletions
@@ -97,5 +97,5 @@ kata_containers_version: 2.2.2
 Debug is disabled by default for all the components of Kata Containers. You can change this behaviour with the following configuration:

 ```yaml
-kata_containers_qemu_debug: 'false'
+kata_containers_qemu_debug: 'true'
 ```
@@ -32,7 +32,7 @@ Based on the table below and the available python version for your ansible host

 |  Ansible Version  | Python Version |
 |-------------------|----------------|
-| >=2.18.0, <2.19.0 | 3.11-3.13      |
+| >=2.19.0, <2.20.0 | 3.11-3.13      |

 ## Customize Ansible vars

@@ -46,6 +46,8 @@ Kubespray expects users to use one of the following variables sources for settin
 | **extra vars** (always win precedence) | override with ``ansible-playbook -e @foo.yml``                               |

 > Extra vars are best used to override kubespray internal variables, for instances, roles/vars/. Those vars are usually **not expected** (by Kubespray developers) to be modified by end users, and not part of Kubespray interface. Thus they can change, disappear, or break stuff unexpectedly.
+>
+> `-e key=value` always passes strings. Since Ansible 12 (ansible-core 2.19), conditionals must return booleans. Pass booleans using JSON syntax instead, e.g. `-e '{"drain_nodes": true}'`. See the [Ansible 12 porting guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_12.html#broken-conditionals).

 ## Ansible tags

@@ -171,7 +173,7 @@ or upgrading related stuff or trying to upload container to K8s cluster nodes:

 ```ShellSession
 ansible-playbook -i inventory/sample/inventory.ini cluster.yml \
-    -e download_run_once=true -e download_localhost=true \
+    -e '{"download_run_once": true, "download_localhost": true}' \
    --tags download --skip-tags upload,upgrade
 ```

@@ -60,10 +60,7 @@ ansible-playbook -i inventory/mycluster/inventory.ini remove-node.yml -b -v \

 > Note: The playbook does not currently support the removal of the first control plane or etcd node. These nodes are essential for maintaining cluster operations and must remain intact.

-If a node is completely unreachable by ssh, add `--extra-vars reset_nodes=false`
-to skip the node reset step. If one node is unavailable, but others you wish
-to remove are able to connect via SSH, you could set `reset_nodes=false` as a host
-var in inventory.
+If a node is completely unreachable by ssh, add `--extra-vars '{"reset_nodes": false}'` to skip the node reset step. If one node is unavailable, but others you wish to remove are able to connect via SSH, you could set `reset_nodes=False` as a host var in inventory.

 ## Connecting to Kubernetes

@@ -18,7 +18,7 @@ Before using `--limit` run playbook `facts.yml` without the limit to refresh fac

 With the old node still in the inventory, run `remove-node.yml`. You need to pass `-e node=NODE_NAME` to the playbook to limit the execution to the node being removed.

-If the node you want to remove is not online, you should add `reset_nodes=false` and `allow_ungraceful_removal=true` to your extra-vars: `-e node=NODE_NAME -e reset_nodes=false -e allow_ungraceful_removal=true`.
+If the node you want to remove is not online, you should add the `reset_nodes` and `allow_ungraceful_removal` booleans to your extra-vars: `-e node=NODE_NAME -e '{"reset_nodes": false, "allow_ungraceful_removal": true}'`.
 Use this flag even when you remove other types of nodes like a control plane or etcd nodes.

 ### 4) Remove the node from the inventory
@@ -48,7 +48,7 @@ crictl ps | grep nginx-proxy | awk '{print $1}' | xargs crictl stop
 ### 3) Remove old control plane nodes

 With the old node still in the inventory, run `remove-node.yml`. You need to pass `-e node=NODE_NAME` to the playbook to limit the execution to the node being removed.
-If the node you want to remove is not online, you should add `reset_nodes=false` and `allow_ungraceful_removal=true` to your extra-vars.
+If the node you want to remove is not online, you should add the `reset_nodes` and `allow_ungraceful_removal` booleans to your extra-vars: `-e '{"reset_nodes": false, "allow_ungraceful_removal": true}'`.

 ## Adding/Removal of first `kube_control_plane` and etcd-master

@@ -109,7 +109,7 @@ run `upgrade-cluster.yml` or `cluster.yml`. Now you are good to go on with the r
 ### 3) Remove old first control plane node from cluster

 With the old node still in the inventory, run `remove-node.yml`. You need to pass `-e node=node-1` to the playbook to limit the execution to the node being removed.
-If the node you want to remove is not online, you should add `reset_nodes=false` and `allow_ungraceful_removal=true` to your extra-vars.
+If the node you want to remove is not online, you should add the `reset_nodes` and `allow_ungraceful_removal` booleans to your extra-vars: `-e '{"reset_nodes": false, "allow_ungraceful_removal": true}'`.

 ### 4) Edit cluster-info configmap in kube-public namespace

@@ -129,10 +129,10 @@ You need to make sure there are always an odd number of etcd nodes in the cluste

 ### 1) Add the new node running cluster.yml

-Update the inventory and run `cluster.yml` passing `--limit=etcd,kube_control_plane -e ignore_assert_errors=yes`.
+Update the inventory and run `cluster.yml` passing `--limit=etcd,kube_control_plane -e '{"ignore_assert_errors": true}'`.
 If the node you want to add as an etcd node is already a worker or control plane node in your cluster, you have to remove him first using `remove-node.yml`.

-Run `upgrade-cluster.yml` also passing `--limit=etcd,kube_control_plane -e ignore_assert_errors=yes`. This is necessary to update all etcd configuration in the cluster.
+Run `upgrade-cluster.yml` also passing `--limit=etcd,kube_control_plane -e '{"ignore_assert_errors": true}'`. This is necessary to update all etcd configuration in the cluster.

 At this point, you will have an even number of nodes.
 Everything should still be working, and you should only have problems if the cluster decides to elect a new etcd leader before you remove a node.
@@ -150,7 +150,7 @@ In every control plane node, edit `/etc/kubernetes/manifests/kube-apiserver.yaml
 ### 1) Remove an old etcd node

 With the node still in the inventory, run `remove-node.yml` passing `-e node=NODE_NAME` as the name of the node that should be removed.
-If the node you want to remove is not online, you should add `reset_nodes=false` and `allow_ungraceful_removal=true` to your extra-vars.
+If the node you want to remove is not online, you should add the `reset_nodes` and `allow_ungraceful_removal` booleans to your extra-vars: `-e '{"reset_nodes": false, "allow_ungraceful_removal": true}'`.

 ### 2) Make sure only remaining nodes are in your inventory

@@ -9,7 +9,7 @@ following artifacts in advance from another environment where has access to the
 * Container images used by Kubespray. Exhaustive list depends on your setup
 * [Optional] Python packages used by Kubespray (only required if your OS doesn't provide all python packages/versions
  listed in `requirements.txt`)
-* [Optional] Helm chart files (only required if `helm_enabled=true`)
+* [Optional] Helm chart files (only required if `helm_enabled: true`)

 Then you need to setup the following services on your offline environment:

@@ -26,16 +26,16 @@ If you wanted to upgrade just kube_version from v1.18.10 to v1.19.7, you could
 deploy the following way:

 ```ShellSession
-ansible-playbook cluster.yml -i inventory/sample/inventory.ini -e kube_version=1.18.10 -e upgrade_cluster_setup=true
+ansible-playbook cluster.yml -i inventory/sample/inventory.ini -e kube_version=1.18.10 -e '{"upgrade_cluster_setup": true}'
 ```

 And then repeat with 1.19.7 as kube_version:

 ```ShellSession
-ansible-playbook cluster.yml -i inventory/sample/inventory.ini -e kube_version=1.19.7 -e upgrade_cluster_setup=true
+ansible-playbook cluster.yml -i inventory/sample/inventory.ini -e kube_version=1.19.7 -e '{"upgrade_cluster_setup": true}'
 ```

-The var ```-e upgrade_cluster_setup=true``` is needed to be set in order to migrate the deploys of e.g kube-apiserver inside the cluster immediately which is usually only done in the graceful upgrade. (Refer to [#4139](https://github.com/kubernetes-sigs/kubespray/issues/4139) and [#4736](https://github.com/kubernetes-sigs/kubespray/issues/4736))
+The var ```-e '{"upgrade_cluster_setup": true}'``` is needed to be set in order to migrate the deploys of e.g kube-apiserver inside the cluster immediately which is usually only done in the graceful upgrade. (Refer to [#4139](https://github.com/kubernetes-sigs/kubespray/issues/4139) and [#4736](https://github.com/kubernetes-sigs/kubespray/issues/4736))

 ## Graceful upgrade

@@ -430,7 +430,7 @@ As of Kubespray 2.18.0, containerd is already the default container engine. If y
 If you want to upgrade the APT or YUM packages while the nodes are cordoned, you can use:

 ```ShellSession
-ansible-playbook upgrade-cluster.yml -b -i inventory/sample/inventory.ini -e system_upgrade=true
+ansible-playbook upgrade-cluster.yml -b -i inventory/sample/inventory.ini -e '{"system_upgrade": true}'
 ```

 Nodes will be rebooted when there are package upgrades (`system_upgrade_reboot: on-upgrade`).