Skip to content

Commit 05167d0

Browse files
jjqq2013jjqq2013
committed
Fix typos. Add docs about execution order of Cloud-init files, steps, and substeps
Signed-off-by: jjqq2013 <[email protected]>
1 parent 33f51de commit 05167d0

File tree

2 files changed

+96
-3
lines changed

2 files changed

+96
-3
lines changed

‎docs/content/en/docs/Customizing/stages.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,35 @@ We have a custom augmented cloud-init syntax that allows to hook into various st
1414
- Network availability
1515
- During upgrades, installation, deployments , and resets
1616

17-
Cloud-init files in `/system/oem`, `/oem` and `/usr/local/oem` are applied in 5 different phases: `boot`, `network`, `fs`, `initramfs` and `reconcile`. All the available cloud-init keywords can be used in each stage. Additionally, it's possible also to hook before or after a stage has run, each one has a specific stage which is possible to run steps: `boot.after`, `network.before`, `fs.after` etc.
17+
Cloud-init files in `/system/oem`, `/oem`, `/usr/local/oem`, and kernel boot args are applied in 5 different stages: `boot`, `network`, `fs`, `initramfs` and `reconcile`. All the available cloud-init keywords can be used in each stage. Additionally, it's possible also to hook before or after a stage has run, each one has a specific stage which is possible to run steps: `boot.after`, `network.before`, `fs.after` etc.
1818

1919
Multiple stages can be specified in a single cloud-init file.
2020

21+
File extension name must be *.yaml or *.yml.
22+
2123
{{% alert title="Note" %}}
22-
When a Elemental derivative boots it creates sentinel files in order to allow to execute cloud-init steps programmaticaly.
24+
When an Elemental derivative boots it creates sentinel files in order to allow executing cloud-init steps programmatically.
2325

2426
- `/run/cos/recovery_mode` is being created when booting from the recovery partition
2527
- `/run/cos/live_mode` is created when booting from the LiveCD
2628

2729
To execute a block using the sentinel files you can specify: `if: '[ -f "/run/cos/..." ]'`, see the examples below.
2830
{{% /alert %}}
2931

32+
At every stage, Elemental derivative parse and execute Cloud-init files in the following order:
33+
- `/system/oem` (Cannot be modified by users)
34+
- `/oem` (Can be modified by users)
35+
- `/usr/local/oem` (Can be modified by users)
36+
- Cloud-init config URL specified in kernel boot args, e.g., elemental.setup=http://example.com/cloudinit.cfg
37+
- Cloud-init config encoded in kernel boot args, e.g., stages.network[0].authorized_keys.user=github:user
38+
39+
In each above directory, files are processed in the lexical order of file name.
40+
41+
Unlike the standard Cloud-init, which merges all config files before execution, Elemental derivative executes
42+
Cloud-init files one by one.
43+
44+
Therefore, definitions in later Cloud-init files override what previous files defined, partially or completely.
45+
3046
## Stages
3147

3248
Below there is a detailed list of the stages available that can be used in the cloud-init configuration files

‎docs/content/en/docs/Reference/cloud_init.md‎

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,84 @@ stages:
8585
The default cloud-config format is split into *stages* (*initramfs*, *boot*, *network*, *initramfs*, *reconcile*, called generically **STAGE_ID** below) [see also stages](../../customizing/stages) that are emitted internally during the various phases by calling `cos-setup STAGE_ID`.
8686
*steps* (**STEP_NAME** below) defined for each stage are executed in order.
8787

88-
Each cloud-config file is loaded and executed only at the apprioriate stage, this allows further components to emit their own stages at the desired time.
88+
Each cloud-config file is loaded and executed only at the appropriate stage, this allows further components to emit their own stages at the desired time.
89+
90+
_Note_:
91+
- The execution order of multiple `substeps` within a single `step` might be not what you think, especially whether the `commands` are executed after other substeps. For example:
92+
```
93+
stages:
94+
fs:
95+
- name: test
96+
environment_file: /tmp/env_file1
97+
environment:
98+
ENV1: this is ENV1
99+
files:
100+
- path: /tmp/file1
101+
content: "this is file1\n"
102+
directories:
103+
- path: /tmp/dir1
104+
users:
105+
user1:
106+
passwd: password
107+
commands:
108+
- |
109+
bash -x >> /tmp/log 2>&1 <<'EOF'
110+
ls -lFd /tmp/env_file1
111+
printenv ENV1
112+
ls -lFd /tmp/file1
113+
ls -lFd /tmp/dir1
114+
id user1
115+
EOF
116+
```
117+
118+
You might expect that when the `commands` get executed, all things defined above it has been executed, such as the user1 has been created.
119+
But it is not. As of now, the output (/tmp/log) is:
120+
```
121+
+ ls -lFd /tmp/env_file1
122+
ls: cannot access '/tmp/env_file1': No such file or directory
123+
+ printenv ENV1
124+
this is ENV1
125+
+ ls -lFd /tmp/file1
126+
---------- 1 root root 14 Aug 6 07:13 /tmp/file1
127+
+ ls -lFd /tmp/dir1
128+
d--------- 2 root root 40 Aug 6 07:13 /tmp/dir1/
129+
+ id user1
130+
id: ‘user1’: no such user
131+
```
132+
133+
The internal order is depending on the implementation, see https://github.com/rancher/elemental-toolkit/blob/d8450e01b9119b76670421880070d2cc7fa5f936/pkg/cloudinit/cloudinit.go#L52.
134+
You can see that the `plugins.User` is behind `plugins.Commands`.
135+
136+
Therefore, to make sure the order is what you want, you may split the `substeps` into multiple `steps`, for example:
137+
```
138+
stages:
139+
fs:
140+
- name: step1
141+
environment_file: /tmp/env_file1
142+
environment:
143+
ENV1: this is ENV1
144+
files:
145+
- path: /tmp/file1
146+
content: "this is file1\n"
147+
directories:
148+
- path: /tmp/dir1
149+
users:
150+
user1:
151+
passwd: password
152+
- name: step2
153+
commands:
154+
- |
155+
bash -x >> /tmp/log 2>&1 <<'EOF'
156+
ls -lFd /tmp/env_file1
157+
printenv ENV1
158+
ls -lFd /tmp/file1
159+
ls -lFd /tmp/dir1
160+
id user1
161+
EOF
162+
```
163+
164+
- The name of `steps` and output of `substeps` will be output to system journal log which can be viewed by the command `journalctl -u 'elemental*'`.
165+
- It is highly recommended to declare the `name` property of *steps*, so that it will be easier to investigate the output of `journalctl -u 'elemental*'` by the name.
89166

90167
{{% pageinfo %}}
91168
The [cloud-init tool](https://github.com/mudler/yip#readme) can be also run standalone, this helps debugging locally and also during development, you can find separate [releases here](https://github.com/mudler/yip/releases).

0 commit comments

Comments
 (0)