From 2af9b1cc94ac9b1bb6afaaad791f5ad9d284c421 Mon Sep 17 00:00:00 2001 From: Shashank Varma Date: Sun, 20 Sep 2026 01:05:59 -0500 Subject: [PATCH] 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 --------- Signed-off-by: Shashank Varma <324153016+shashankvarma499@users.noreply.github.com> Signed-off-by: Kay Yan Co-authored-by: Shashank Varma <324153016+shashankvarma499@users.noreply.github.com> Co-authored-by: Kay Yan --- docs/CRI/kata-containers.md | 2 +- docs/ansible/ansible.md | 6 ++++-- docs/getting_started/getting-started.md | 5 +---- docs/operations/nodes.md | 12 ++++++------ docs/operations/offline-environment.md | 2 +- docs/operations/upgrades.md | 8 ++++---- 6 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/CRI/kata-containers.md b/docs/CRI/kata-containers.md index 30843fd7f..cb555191f 100644 --- a/docs/CRI/kata-containers.md +++ b/docs/CRI/kata-containers.md @@ -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' ``` diff --git a/docs/ansible/ansible.md b/docs/ansible/ansible.md index 2edcaf997..d17e3e44e 100644 --- a/docs/ansible/ansible.md +++ b/docs/ansible/ansible.md @@ -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 ``` diff --git a/docs/getting_started/getting-started.md b/docs/getting_started/getting-started.md index ceba73b48..67cccd0ba 100644 --- a/docs/getting_started/getting-started.md +++ b/docs/getting_started/getting-started.md @@ -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 diff --git a/docs/operations/nodes.md b/docs/operations/nodes.md index 5e6941f5f..39cd8d6fd 100644 --- a/docs/operations/nodes.md +++ b/docs/operations/nodes.md @@ -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 diff --git a/docs/operations/offline-environment.md b/docs/operations/offline-environment.md index f4895dcec..208ed7025 100644 --- a/docs/operations/offline-environment.md +++ b/docs/operations/offline-environment.md @@ -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: diff --git a/docs/operations/upgrades.md b/docs/operations/upgrades.md index 2fec2b061..494f0e23f 100644 --- a/docs/operations/upgrades.md +++ b/docs/operations/upgrades.md @@ -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`).