Doc: improve documentation on merging user data sections

[zhhuabj]

Bug report

I am following the doc [1] to merge two user data, but it doesn't work.

[1] https://cloudinit.readthedocs.io/en/latest/reference/merging.html#example-cloud-config

Steps to reproduce the problem

Here are my steps to reproduce this problem.

1, create a lxd test container with my-user-data.yaml

cat << EOF |tee /tmp/my-user-data.yaml 
#cloud-config
merge_how:
 - name: list
   settings: [append]
 - name: dict
   settings: [no_replace, recurse_list]
runcmd:
- echo 'running command with runcmd from userdata' >> /var/log/cloud-init.log
EOF
lxc launch ubuntu:jammy test --config=user.user-data="$(cat /tmp/my-user-data.yaml)"

root@test:~# grep -r 'running command' /var/log/cloud-init.log 
running command with runcmd from userdata

2, create another user-data (/etc/cloud/cloud.cfg.d/91_my.cfg) inside lxd container

cat << EOF |tee /etc/cloud/cloud.cfg.d/91_my.cfg
#cloud-config
merge_how:
 - name: list
   settings: [append]
 - name: dict
   settings: [no_replace, recurse_list]
runcmd:
- echo 'running command with runcmd from userdata' >> /var/log/cloud-init.log
EOF

3, restaart lxd container inside lxd container

cloud-init clean --logs --reboot

4, relogin lxd container again with 'lxc shell test', confirm both /etc/cloud/cloud.cfg.d/91_my.cfg and /var/lib/cloud/instances/90a1a29a-1f70-471a-a920-d1a6919270d0/user-data.txt are there

root@test:~# cat /etc/cloud/cloud.cfg.d/91_my.cfg 
#cloud-config
merge_how:
 - name: list
   settings: [append]
 - name: dict
   settings: [no_replace, recurse_list]
runcmd:
- echo 'running command with runcmd from userdata' >> /var/log/cloud-init.log    
root@test:~# cat /var/lib/cloud/instances/90a1a29a-1f70-471a-a920-d1a6919270d0/user-data.txt
#cloud-config
merge_how:
 - name: list
   settings: [append]
 - name: dict
   settings: [no_replace, recurse_list]
runcmd:
- echo 'running command with runcmd from userdata' >> /var/log/cloud-init.log

5, but the file /var/lib/cloud/instances/90a1a29a-1f70-471a-a920-d1a6919270d0/user-data.txt just override the file /etc/cloud/cloud.cfg.d/91_my.cfg, they haven't merged.

root@test:~# grep -r 'running command' /var/log/cloud-init.log 
running command with runcmd from userdata

6, continue to do some checks

root@test:~# cloud-init query userdata
#cloud-config
merge_how:
 - name: list
   settings: [append]
 - name: dict
   settings: [no_replace, recurse_list]
runcmd:
- echo 'running command with runcmd from userdata' >> /var/log/cloud-init.log

root@test:~# cloud-init schema --system --annotate
Found cloud-config data types: user-data, network-config

1. user-data at /var/lib/cloud/instances/90a1a29a-1f70-471a-a920-d1a6919270d0/cloud-config.txt:
  Valid schema user-data

2. network-config at /var/lib/cloud/instances/90a1a29a-1f70-471a-a920-d1a6919270d0/network-config.json:
  Valid schema network-config

Environment details

• Cloud-init version: 23.4.4-0ubuntu0~22.04.1
• Operating System Distribution: ubuntu 22.04
• Cloud provider, platform or installer type: lxd

cloud-init logs

cloud-init.log

[aciba90]

Thanks, @zhhuabj, for reporting this.

What you are trying to configure how to merge is the base-config with the user-data, and that cannot be achieved currently. They are plainly merged, user-data taking priority and overwriting the overlapping parts over the base-config.

This is explained in the documentation:

https://cloudinit.readthedocs.io/en/latest/reference/merging.html#other-uses Note, however, that merge algorithms are not used across configuration types. As was the case before merging was implemented, user data will overwrite 'conf.d' configuration without merging.

I am going to leave this ticket open to give more visibility on the docs to that note, and clarify it if possible.

Regarding merging base-config and user-data, there have been and are discussions/evaluations around extending cloud-init to let users define how vendor-data and user-data are merged. The team will take into account this.

[zhhuabj]

Hi @aciba90, thanks for your reply