External-Mirrors/kubespray
2
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kubespray.git synced 2026-10-29 22:03:22 -02:30
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Shashank Varma
2026-09-20 06:05:59 +00:00
committed by GitHub
co-authored by Shashank Varma Kay Yan
parent b8ad8289a8
commit 2af9b1cc94
6 changed files with 17 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CRI/kata-containers.md
+1 -1
View File
@@ -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'
```
docs/ansible/ansible.md
+4 -2
View File
@@ -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
```
docs/getting_started/getting-started.md
+1 -4
View File
@@ -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
docs/operations/nodes.md
+6 -6
View File
@@ -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
docs/operations/offline-environment.md
+1 -1
View File
@@ -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:
docs/operations/upgrades.md
+4 -4
View File
@@ -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`).