Merge ~powersj/cloud-init:docs/cli into cloud-init:master
- Git
- lp:~powersj/cloud-init
- docs/cli
- Merge into master
Proposed by
Joshua Powers
Status: | Merged |
---|---|
Approved by: | Chad Smith |
Approved revision: | c62f96299293afcae0dab000a1888aaf1016d900 |
Merge reported by: | Server Team CI bot |
Merged at revision: | not available |
Proposed branch: | ~powersj/cloud-init:docs/cli |
Merge into: | cloud-init:master |
Diff against target: |
616 lines (+304/-300) 2 files modified
dev/null (+0/-300) doc/rtd/topics/cli.rst (+304/-0) |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Chad Smith | Approve | ||
Server Team CI bot | continuous-integration | Approve | |
Review via email: mp+372648@code.launchpad.net |
Commit message
docs: create cli specific page
This is formerly the capabilities page.
Description of the change
To post a comment you must log in.
Revision history for this message
Server Team CI bot (server-team-bot) wrote : | # |
review:
Approve
(continuous-integration)
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst | |||
2 | 0 | deleted file mode 100644 | 0 | deleted file mode 100644 |
3 | index 6d85a99..0000000 | |||
4 | --- a/doc/rtd/topics/capabilities.rst | |||
5 | +++ /dev/null | |||
6 | @@ -1,300 +0,0 @@ | |||
7 | 1 | .. _capabilities: | ||
8 | 2 | |||
9 | 3 | ************ | ||
10 | 4 | Capabilities | ||
11 | 5 | ************ | ||
12 | 6 | |||
13 | 7 | - Setting a default locale | ||
14 | 8 | - Setting an instance hostname | ||
15 | 9 | - Generating instance SSH private keys | ||
16 | 10 | - Adding SSH keys to a user's ``.ssh/authorized_keys`` so they can log in | ||
17 | 11 | - Setting up ephemeral mount points | ||
18 | 12 | - Configuring network devices | ||
19 | 13 | |||
20 | 14 | User configurability | ||
21 | 15 | ==================== | ||
22 | 16 | |||
23 | 17 | `Cloud-init`_ 's behavior can be configured via user-data. | ||
24 | 18 | |||
25 | 19 | User-data can be given by the user at instance launch time. See | ||
26 | 20 | :ref:`user_data_formats` for acceptable user-data content. | ||
27 | 21 | |||
28 | 22 | |||
29 | 23 | This is done via the ``--user-data`` or ``--user-data-file`` argument to | ||
30 | 24 | ec2-run-instances for example. | ||
31 | 25 | |||
32 | 26 | * Check your local client's documentation for how to provide a `user-data` | ||
33 | 27 | string or `user-data` file to cloud-init on instance creation. | ||
34 | 28 | |||
35 | 29 | |||
36 | 30 | Feature detection | ||
37 | 31 | ================= | ||
38 | 32 | |||
39 | 33 | Newer versions of cloud-init may have a list of additional features that they | ||
40 | 34 | support. This allows other applications to detect what features the installed | ||
41 | 35 | cloud-init supports without having to parse its version number. If present, | ||
42 | 36 | this list of features will be located at ``cloudinit.version.FEATURES``. | ||
43 | 37 | |||
44 | 38 | Currently defined feature names include: | ||
45 | 39 | |||
46 | 40 | - ``NETWORK_CONFIG_V1`` support for v1 networking configuration, | ||
47 | 41 | see :ref:`network_config_v1` documentation for examples. | ||
48 | 42 | - ``NETWORK_CONFIG_V2`` support for v2 networking configuration, | ||
49 | 43 | see :ref:`network_config_v2` documentation for examples. | ||
50 | 44 | |||
51 | 45 | |||
52 | 46 | CLI Interface | ||
53 | 47 | ============= | ||
54 | 48 | |||
55 | 49 | The command line documentation is accessible on any cloud-init installed | ||
56 | 50 | system: | ||
57 | 51 | |||
58 | 52 | .. code-block:: shell-session | ||
59 | 53 | |||
60 | 54 | % cloud-init --help | ||
61 | 55 | usage: cloud-init [-h] [--version] [--file FILES] | ||
62 | 56 | [--debug] [--force] | ||
63 | 57 | {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} | ||
64 | 58 | ... | ||
65 | 59 | |||
66 | 60 | optional arguments: | ||
67 | 61 | -h, --help show this help message and exit | ||
68 | 62 | --version, -v show program's version number and exit | ||
69 | 63 | --file FILES, -f FILES | ||
70 | 64 | additional yaml configuration files to use | ||
71 | 65 | --debug, -d show additional pre-action logging (default: False) | ||
72 | 66 | --force force running even if no datasource is found (use at | ||
73 | 67 | your own risk) | ||
74 | 68 | |||
75 | 69 | Subcommands: | ||
76 | 70 | {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} | ||
77 | 71 | init initializes cloud-init and performs initial modules | ||
78 | 72 | modules activates modules using a given configuration key | ||
79 | 73 | single run a single module | ||
80 | 74 | query Query instance metadata from the command line | ||
81 | 75 | dhclient-hook run the dhclient hookto record network info | ||
82 | 76 | features list defined features | ||
83 | 77 | analyze Devel tool: Analyze cloud-init logs and data | ||
84 | 78 | devel Run development tools | ||
85 | 79 | collect-logs Collect and tar all cloud-init debug info | ||
86 | 80 | clean Remove logs and artifacts so cloud-init can re-run | ||
87 | 81 | status Report cloud-init status or wait on completion | ||
88 | 82 | |||
89 | 83 | |||
90 | 84 | CLI Subcommand details | ||
91 | 85 | ====================== | ||
92 | 86 | |||
93 | 87 | .. _cli_features: | ||
94 | 88 | |||
95 | 89 | cloud-init features | ||
96 | 90 | ------------------- | ||
97 | 91 | Print out each feature supported. If cloud-init does not have the | ||
98 | 92 | features subcommand, it also does not support any features described in | ||
99 | 93 | this document. | ||
100 | 94 | |||
101 | 95 | .. code-block:: shell-session | ||
102 | 96 | |||
103 | 97 | % cloud-init features | ||
104 | 98 | NETWORK_CONFIG_V1 | ||
105 | 99 | NETWORK_CONFIG_V2 | ||
106 | 100 | |||
107 | 101 | .. _cli_status: | ||
108 | 102 | |||
109 | 103 | cloud-init status | ||
110 | 104 | ----------------- | ||
111 | 105 | Report whether cloud-init is running, done, disabled or errored. Exits | ||
112 | 106 | non-zero if an error is detected in cloud-init. | ||
113 | 107 | |||
114 | 108 | * **--long**: Detailed status information. | ||
115 | 109 | * **--wait**: Block until cloud-init completes. | ||
116 | 110 | |||
117 | 111 | .. code-block:: shell-session | ||
118 | 112 | |||
119 | 113 | % cloud-init status --long | ||
120 | 114 | status: done | ||
121 | 115 | time: Wed, 17 Jan 2018 20:41:59 +0000 | ||
122 | 116 | detail: | ||
123 | 117 | DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] | ||
124 | 118 | |||
125 | 119 | # Cloud-init running still short versus long options | ||
126 | 120 | % cloud-init status | ||
127 | 121 | status: running | ||
128 | 122 | % cloud-init status --long | ||
129 | 123 | status: running | ||
130 | 124 | time: Fri, 26 Jan 2018 21:39:43 +0000 | ||
131 | 125 | detail: | ||
132 | 126 | Running in stage: init-local | ||
133 | 127 | |||
134 | 128 | .. _cli_collect_logs: | ||
135 | 129 | |||
136 | 130 | cloud-init collect-logs | ||
137 | 131 | ----------------------- | ||
138 | 132 | Collect and tar cloud-init generated logs, data files and system | ||
139 | 133 | information for triage. This subcommand is integrated with apport. | ||
140 | 134 | |||
141 | 135 | **Note**: Ubuntu users can file bugs with `ubuntu-bug cloud-init` to | ||
142 | 136 | automaticaly attach these logs to a bug report. | ||
143 | 137 | |||
144 | 138 | Logs collected are: | ||
145 | 139 | |||
146 | 140 | * /var/log/cloud-init*log | ||
147 | 141 | * /run/cloud-init | ||
148 | 142 | * cloud-init package version | ||
149 | 143 | * dmesg output | ||
150 | 144 | * journalctl output | ||
151 | 145 | * /var/lib/cloud/instance/user-data.txt | ||
152 | 146 | |||
153 | 147 | .. _cli_query: | ||
154 | 148 | |||
155 | 149 | cloud-init query | ||
156 | 150 | ------------------ | ||
157 | 151 | Query standardized cloud instance metadata crawled by cloud-init and stored | ||
158 | 152 | in ``/run/cloud-init/instance-data.json``. This is a convenience command-line | ||
159 | 153 | interface to reference any cached configuration metadata that cloud-init | ||
160 | 154 | crawls when booting the instance. See :ref:`instance_metadata` for more info. | ||
161 | 155 | |||
162 | 156 | * **--all**: Dump all available instance data as json which can be queried. | ||
163 | 157 | * **--instance-data**: Optional path to a different instance-data.json file to | ||
164 | 158 | source for queries. | ||
165 | 159 | * **--list-keys**: List available query keys from cached instance data. | ||
166 | 160 | |||
167 | 161 | .. code-block:: shell-session | ||
168 | 162 | |||
169 | 163 | # List all top-level query keys available (includes standardized aliases) | ||
170 | 164 | % cloud-init query --list-keys | ||
171 | 165 | availability_zone | ||
172 | 166 | base64_encoded_keys | ||
173 | 167 | cloud_name | ||
174 | 168 | ds | ||
175 | 169 | instance_id | ||
176 | 170 | local_hostname | ||
177 | 171 | region | ||
178 | 172 | v1 | ||
179 | 173 | |||
180 | 174 | * **<varname>**: A dot-delimited variable path into the instance-data.json | ||
181 | 175 | object. | ||
182 | 176 | |||
183 | 177 | .. code-block:: shell-session | ||
184 | 178 | |||
185 | 179 | # Query cloud-init standardized metadata on any cloud | ||
186 | 180 | % cloud-init query v1.cloud_name | ||
187 | 181 | aws # or openstack, azure, gce etc. | ||
188 | 182 | |||
189 | 183 | # Any standardized instance-data under a <v#> key is aliased as a top-level | ||
190 | 184 | # key for convenience. | ||
191 | 185 | % cloud-init query cloud_name | ||
192 | 186 | aws # or openstack, azure, gce etc. | ||
193 | 187 | |||
194 | 188 | # Query datasource-specific metadata on EC2 | ||
195 | 189 | % cloud-init query ds.meta_data.public_ipv4 | ||
196 | 190 | |||
197 | 191 | * **--format** A string that will use jinja-template syntax to render a string | ||
198 | 192 | replacing | ||
199 | 193 | |||
200 | 194 | .. code-block:: shell-session | ||
201 | 195 | |||
202 | 196 | # Generate a custom hostname fqdn based on instance-id, cloud and region | ||
203 | 197 | % cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com' | ||
204 | 198 | custom-i-0e91f69987f37ec74.us-east-2.aws.com | ||
205 | 199 | |||
206 | 200 | |||
207 | 201 | .. note:: | ||
208 | 202 | The standardized instance data keys under **v#** are guaranteed not to change | ||
209 | 203 | behavior or format. If using top-level convenience aliases for any | ||
210 | 204 | standardized instance data keys, the most value (highest **v#**) of that key | ||
211 | 205 | name is what is reported as the top-level value. So these aliases act as a | ||
212 | 206 | 'latest'. | ||
213 | 207 | |||
214 | 208 | |||
215 | 209 | .. _cli_analyze: | ||
216 | 210 | |||
217 | 211 | cloud-init analyze | ||
218 | 212 | ------------------ | ||
219 | 213 | Get detailed reports of where cloud-init spends most of its time. See | ||
220 | 214 | :ref:`boot_time_analysis` for more info. | ||
221 | 215 | |||
222 | 216 | * **blame** Report ordered by most costly operations. | ||
223 | 217 | * **dump** Machine-readable JSON dump of all cloud-init tracked events. | ||
224 | 218 | * **show** show time-ordered report of the cost of operations during each | ||
225 | 219 | boot stage. | ||
226 | 220 | * **boot** show timestamps from kernel initialization, kernel finish initialization, and cloud-init start. | ||
227 | 221 | |||
228 | 222 | .. _cli_devel: | ||
229 | 223 | |||
230 | 224 | cloud-init devel | ||
231 | 225 | ---------------- | ||
232 | 226 | Collection of development tools under active development. These tools will | ||
233 | 227 | likely be promoted to top-level subcommands when stable. | ||
234 | 228 | |||
235 | 229 | * ``cloud-init devel schema``: A **#cloud-config** format and schema | ||
236 | 230 | validator. It accepts a cloud-config yaml file and annotates potential | ||
237 | 231 | schema errors locally without the need for deployment. Schema | ||
238 | 232 | validation is work in progress and supports a subset of cloud-config | ||
239 | 233 | modules. | ||
240 | 234 | |||
241 | 235 | * ``cloud-init devel render``: Use cloud-init's jinja template render to | ||
242 | 236 | process **#cloud-config** or **custom-scripts**, injecting any variables | ||
243 | 237 | from ``/run/cloud-init/instance-data.json``. It accepts a user-data file | ||
244 | 238 | containing the jinja template header ``## template: jinja`` and renders | ||
245 | 239 | that content with any instance-data.json variables present. | ||
246 | 240 | |||
247 | 241 | |||
248 | 242 | .. _cli_clean: | ||
249 | 243 | |||
250 | 244 | cloud-init clean | ||
251 | 245 | ---------------- | ||
252 | 246 | Remove cloud-init artifacts from /var/lib/cloud and optionally reboot the | ||
253 | 247 | machine to so cloud-init re-runs all stages as it did on first boot. | ||
254 | 248 | |||
255 | 249 | * **--logs**: Optionally remove /var/log/cloud-init*log files. | ||
256 | 250 | * **--reboot**: Reboot the system after removing artifacts. | ||
257 | 251 | |||
258 | 252 | .. _cli_init: | ||
259 | 253 | |||
260 | 254 | cloud-init init | ||
261 | 255 | --------------- | ||
262 | 256 | Generally run by OS init systems to execute cloud-init's stages | ||
263 | 257 | *init* and *init-local*. See :ref:`boot_stages` for more info. | ||
264 | 258 | Can be run on the commandline, but is generally gated to run only once | ||
265 | 259 | due to semaphores in **/var/lib/cloud/instance/sem/** and | ||
266 | 260 | **/var/lib/cloud/sem**. | ||
267 | 261 | |||
268 | 262 | * **--local**: Run *init-local* stage instead of *init*. | ||
269 | 263 | |||
270 | 264 | .. _cli_modules: | ||
271 | 265 | |||
272 | 266 | cloud-init modules | ||
273 | 267 | ------------------ | ||
274 | 268 | Generally run by OS init systems to execute *modules:config* and | ||
275 | 269 | *modules:final* boot stages. This executes cloud config :ref:`modules` | ||
276 | 270 | configured to run in the init, config and final stages. The modules are | ||
277 | 271 | declared to run in various boot stages in the file | ||
278 | 272 | **/etc/cloud/cloud.cfg** under keys **cloud_init_modules**, | ||
279 | 273 | **cloud_init_modules** and **cloud_init_modules**. Can be run on the | ||
280 | 274 | commandline, but each module is gated to run only once due to semaphores | ||
281 | 275 | in ``/var/lib/cloud/``. | ||
282 | 276 | |||
283 | 277 | * **--mode (init|config|final)**: Run *modules:init*, *modules:config* or | ||
284 | 278 | *modules:final* cloud-init stages. See :ref:`boot_stages` for more info. | ||
285 | 279 | |||
286 | 280 | .. _cli_single: | ||
287 | 281 | |||
288 | 282 | cloud-init single | ||
289 | 283 | ----------------- | ||
290 | 284 | Attempt to run a single named cloud config module. The following example | ||
291 | 285 | re-runs the cc_set_hostname module ignoring the module default frequency | ||
292 | 286 | of once-per-instance: | ||
293 | 287 | |||
294 | 288 | * **--name**: The cloud-config module name to run | ||
295 | 289 | * **--frequency**: Optionally override the declared module frequency | ||
296 | 290 | with one of (always|once-per-instance|once) | ||
297 | 291 | |||
298 | 292 | .. code-block:: shell-session | ||
299 | 293 | |||
300 | 294 | % cloud-init single --name set_hostname --frequency always | ||
301 | 295 | |||
302 | 296 | **Note**: Mileage may vary trying to re-run each cloud-config module, as | ||
303 | 297 | some are not idempotent. | ||
304 | 298 | |||
305 | 299 | .. _Cloud-init: https://launchpad.net/cloud-init | ||
306 | 300 | .. vi: textwidth=78 | ||
307 | diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst | |||
308 | 301 | new file mode 100644 | 0 | new file mode 100644 |
309 | index 0000000..b32677b | |||
310 | --- /dev/null | |||
311 | +++ b/doc/rtd/topics/cli.rst | |||
312 | @@ -0,0 +1,304 @@ | |||
313 | 1 | .. _cli: | ||
314 | 2 | |||
315 | 3 | CLI Interface | ||
316 | 4 | ************* | ||
317 | 5 | |||
318 | 6 | For the latest list of subcommands and arguments use cloud-init's ``--help`` | ||
319 | 7 | option. This can be used against cloud-init itself or any of its subcommands. | ||
320 | 8 | |||
321 | 9 | .. code-block:: shell-session | ||
322 | 10 | |||
323 | 11 | $ cloud-init --help | ||
324 | 12 | usage: /usr/bin/cloud-init [-h] [--version] [--file FILES] [--debug] [--force] | ||
325 | 13 | {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} | ||
326 | 14 | ... | ||
327 | 15 | |||
328 | 16 | optional arguments: | ||
329 | 17 | -h, --help show this help message and exit | ||
330 | 18 | --version, -v show program's version number and exit | ||
331 | 19 | --file FILES, -f FILES | ||
332 | 20 | additional yaml configuration files to use | ||
333 | 21 | --debug, -d show additional pre-action logging (default: False) | ||
334 | 22 | --force force running even if no datasource is found (use at | ||
335 | 23 | your own risk) | ||
336 | 24 | |||
337 | 25 | Subcommands: | ||
338 | 26 | {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status} | ||
339 | 27 | init initializes cloud-init and performs initial modules | ||
340 | 28 | modules activates modules using a given configuration key | ||
341 | 29 | single run a single module | ||
342 | 30 | query Query standardized instance metadata from the command | ||
343 | 31 | line. | ||
344 | 32 | dhclient-hook Run the dhclient hook to record network info. | ||
345 | 33 | features list defined features | ||
346 | 34 | analyze Devel tool: Analyze cloud-init logs and data | ||
347 | 35 | devel Run development tools | ||
348 | 36 | collect-logs Collect and tar all cloud-init debug info | ||
349 | 37 | clean Remove logs and artifacts so cloud-init can re-run. | ||
350 | 38 | status Report cloud-init status or wait on completion. | ||
351 | 39 | |||
352 | 40 | The rest of this document will give an overview of each of the subcommands. | ||
353 | 41 | |||
354 | 42 | |||
355 | 43 | .. _cli_analyze: | ||
356 | 44 | |||
357 | 45 | analyze | ||
358 | 46 | ======= | ||
359 | 47 | |||
360 | 48 | Get detailed reports of where cloud-init spends its time during the boot | ||
361 | 49 | process. For more complete reference see :ref:`analyze`. | ||
362 | 50 | |||
363 | 51 | Possible subcommands include: | ||
364 | 52 | |||
365 | 53 | * *blame*: report ordered by most costly operations | ||
366 | 54 | * *dump*: machine-readable JSON dump of all cloud-init tracked events | ||
367 | 55 | * *show*: show time-ordered report of the cost of operations during each | ||
368 | 56 | boot stage | ||
369 | 57 | * *boot*: show timestamps from kernel initialization, kernel finish | ||
370 | 58 | initialization, and cloud-init start | ||
371 | 59 | |||
372 | 60 | |||
373 | 61 | .. _cli_clean: | ||
374 | 62 | |||
375 | 63 | clean | ||
376 | 64 | ===== | ||
377 | 65 | |||
378 | 66 | Remove cloud-init artifacts from ``/var/lib/cloud`` to simulate a clean | ||
379 | 67 | instance. On reboot, cloud-init will re-run all stages as it did on first boot. | ||
380 | 68 | |||
381 | 69 | * *\\-\\-logs*: optionally remove all cloud-init log files in ``/var/log/`` | ||
382 | 70 | * *\\-\\-reboot*: reboot the system after removing artifacts | ||
383 | 71 | |||
384 | 72 | |||
385 | 73 | .. _cli_collect_logs: | ||
386 | 74 | |||
387 | 75 | collect-logs | ||
388 | 76 | ============ | ||
389 | 77 | |||
390 | 78 | Collect and tar cloud-init generated logs, data files, and system | ||
391 | 79 | information for triage. This subcommand is integrated with apport. | ||
392 | 80 | |||
393 | 81 | Logs collected include: | ||
394 | 82 | |||
395 | 83 | * ``/var/log/cloud-init.log`` | ||
396 | 84 | * ``/var/log/cloud-init-output.log`` | ||
397 | 85 | * ``/run/cloud-init`` | ||
398 | 86 | * ``/var/lib/cloud/instance/user-data.txt`` | ||
399 | 87 | * cloud-init package version | ||
400 | 88 | * ``dmesg`` output | ||
401 | 89 | * journalctl output | ||
402 | 90 | |||
403 | 91 | .. note:: | ||
404 | 92 | |||
405 | 93 | Ubuntu users can file bugs with ``ubuntu-bug cloud-init`` to | ||
406 | 94 | automatically attach these logs to a bug report | ||
407 | 95 | |||
408 | 96 | |||
409 | 97 | .. _cli_devel: | ||
410 | 98 | |||
411 | 99 | devel | ||
412 | 100 | ===== | ||
413 | 101 | |||
414 | 102 | Collection of development tools under active development. These tools will | ||
415 | 103 | likely be promoted to top-level subcommands when stable. | ||
416 | 104 | |||
417 | 105 | Do **NOT** rely on the output of these commands as they can and will change. | ||
418 | 106 | |||
419 | 107 | Current subcommands: | ||
420 | 108 | |||
421 | 109 | * ``schema``: a **#cloud-config** format and schema | ||
422 | 110 | validator. It accepts a cloud-config yaml file and annotates potential | ||
423 | 111 | schema errors locally without the need for deployment. Schema | ||
424 | 112 | validation is work in progress and supports a subset of cloud-config | ||
425 | 113 | modules. | ||
426 | 114 | |||
427 | 115 | * ``render``: use cloud-init's jinja template render to | ||
428 | 116 | process **#cloud-config** or **custom-scripts**, injecting any variables | ||
429 | 117 | from ``/run/cloud-init/instance-data.json``. It accepts a user-data file | ||
430 | 118 | containing the jinja template header ``## template: jinja`` and renders | ||
431 | 119 | that content with any instance-data.json variables present. | ||
432 | 120 | |||
433 | 121 | |||
434 | 122 | .. _cli_features: | ||
435 | 123 | |||
436 | 124 | features | ||
437 | 125 | ======== | ||
438 | 126 | |||
439 | 127 | Print out each feature supported. If cloud-init does not have the | ||
440 | 128 | features subcommand, it also does not support any features described in | ||
441 | 129 | this document. | ||
442 | 130 | |||
443 | 131 | .. code-block:: shell-session | ||
444 | 132 | |||
445 | 133 | $ cloud-init features | ||
446 | 134 | NETWORK_CONFIG_V1 | ||
447 | 135 | NETWORK_CONFIG_V2 | ||
448 | 136 | |||
449 | 137 | |||
450 | 138 | .. _cli_init: | ||
451 | 139 | |||
452 | 140 | init | ||
453 | 141 | ==== | ||
454 | 142 | |||
455 | 143 | Generally run by OS init systems to execute cloud-init's stages | ||
456 | 144 | *init* and *init-local*. See :ref:`boot_stages` for more info. | ||
457 | 145 | Can be run on the commandline, but is generally gated to run only once | ||
458 | 146 | due to semaphores in ``/var/lib/cloud/instance/sem/`` and | ||
459 | 147 | ``/var/lib/cloud/sem``. | ||
460 | 148 | |||
461 | 149 | * *\\-\\-local*: run *init-local* stage instead of *init* | ||
462 | 150 | |||
463 | 151 | |||
464 | 152 | .. _cli_modules: | ||
465 | 153 | |||
466 | 154 | modules | ||
467 | 155 | ======= | ||
468 | 156 | |||
469 | 157 | Generally run by OS init systems to execute *modules:config* and | ||
470 | 158 | *modules:final* boot stages. This executes cloud config :ref:`modules` | ||
471 | 159 | configured to run in the init, config and final stages. The modules are | ||
472 | 160 | declared to run in various boot stages in the file | ||
473 | 161 | ``/etc/cloud/cloud.cfg`` under keys: | ||
474 | 162 | |||
475 | 163 | * *cloud_init_modules* | ||
476 | 164 | * *cloud_config_modules* | ||
477 | 165 | * *cloud_init_modules* | ||
478 | 166 | |||
479 | 167 | Can be run on the command line, but each module is gated to run only once due | ||
480 | 168 | to semaphores in ``/var/lib/cloud/``. | ||
481 | 169 | |||
482 | 170 | * *\\-\\-mode [init|config|final]*: run *modules:init*, *modules:config* or | ||
483 | 171 | *modules:final* cloud-init stages. See :ref:`boot_stages` for more info. | ||
484 | 172 | |||
485 | 173 | |||
486 | 174 | .. _cli_query: | ||
487 | 175 | |||
488 | 176 | query | ||
489 | 177 | ===== | ||
490 | 178 | |||
491 | 179 | Query standardized cloud instance metadata crawled by cloud-init and stored | ||
492 | 180 | in ``/run/cloud-init/instance-data.json``. This is a convenience command-line | ||
493 | 181 | interface to reference any cached configuration metadata that cloud-init | ||
494 | 182 | crawls when booting the instance. See :ref:`instance_metadata` for more info. | ||
495 | 183 | |||
496 | 184 | * *\\-\\-all*: dump all available instance data as json which can be queried | ||
497 | 185 | * *\\-\\-instance-data*: optional path to a different instance-data.json file | ||
498 | 186 | to source for queries | ||
499 | 187 | * *\\-\\-list-keys*: list available query keys from cached instance data | ||
500 | 188 | * *\\-\\-format*: a string that will use jinja-template syntax to render a | ||
501 | 189 | string replacing | ||
502 | 190 | * *<varname>*: a dot-delimited variable path into the instance-data.json | ||
503 | 191 | object | ||
504 | 192 | |||
505 | 193 | Below demonstrates how to list all top-level query keys that are standardized | ||
506 | 194 | aliases: | ||
507 | 195 | |||
508 | 196 | .. code-block:: shell-session | ||
509 | 197 | |||
510 | 198 | $ cloud-init query --list-keys | ||
511 | 199 | _beta_keys | ||
512 | 200 | availability_zone | ||
513 | 201 | base64_encoded_keys | ||
514 | 202 | cloud_name | ||
515 | 203 | ds | ||
516 | 204 | instance_id | ||
517 | 205 | local_hostname | ||
518 | 206 | platform | ||
519 | 207 | public_ssh_keys | ||
520 | 208 | region | ||
521 | 209 | sensitive_keys | ||
522 | 210 | subplatform | ||
523 | 211 | userdata | ||
524 | 212 | v1 | ||
525 | 213 | vendordata | ||
526 | 214 | |||
527 | 215 | Below demonstrates how to query standardized metadata from clouds: | ||
528 | 216 | |||
529 | 217 | .. code-block:: shell-session | ||
530 | 218 | |||
531 | 219 | % cloud-init query v1.cloud_name | ||
532 | 220 | aws # or openstack, azure, gce etc. | ||
533 | 221 | |||
534 | 222 | # Any standardized instance-data under a <v#> key is aliased as a top-level key for convenience. | ||
535 | 223 | % cloud-init query cloud_name | ||
536 | 224 | aws # or openstack, azure, gce etc. | ||
537 | 225 | |||
538 | 226 | # Query datasource-specific metadata on EC2 | ||
539 | 227 | % cloud-init query ds.meta_data.public_ipv4 | ||
540 | 228 | |||
541 | 229 | .. note:: | ||
542 | 230 | |||
543 | 231 | The standardized instance data keys under **v#** are guaranteed not to change | ||
544 | 232 | behavior or format. If using top-level convenience aliases for any | ||
545 | 233 | standardized instance data keys, the most value (highest **v#**) of that key | ||
546 | 234 | name is what is reported as the top-level value. So these aliases act as a | ||
547 | 235 | 'latest'. | ||
548 | 236 | |||
549 | 237 | This data can then be formatted to generate custom strings or data: | ||
550 | 238 | |||
551 | 239 | .. code-block:: shell-session | ||
552 | 240 | |||
553 | 241 | # Generate a custom hostname fqdn based on instance-id, cloud and region | ||
554 | 242 | % cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com' | ||
555 | 243 | custom-i-0e91f69987f37ec74.us-east-2.aws.com | ||
556 | 244 | |||
557 | 245 | |||
558 | 246 | .. _cli_single: | ||
559 | 247 | |||
560 | 248 | single | ||
561 | 249 | ====== | ||
562 | 250 | |||
563 | 251 | Attempt to run a single named cloud config module. | ||
564 | 252 | |||
565 | 253 | * *\\-\\-name*: the cloud-config module name to run | ||
566 | 254 | * *\\-\\-frequency*: optionally override the declared module frequency | ||
567 | 255 | with one of (always|once-per-instance|once) | ||
568 | 256 | |||
569 | 257 | The following example re-runs the cc_set_hostname module ignoring the module | ||
570 | 258 | default frequency of once-per-instance: | ||
571 | 259 | |||
572 | 260 | .. code-block:: shell-session | ||
573 | 261 | |||
574 | 262 | $ cloud-init single --name set_hostname --frequency always | ||
575 | 263 | |||
576 | 264 | .. note:: | ||
577 | 265 | |||
578 | 266 | Mileage may vary trying to re-run each cloud-config module, as | ||
579 | 267 | some are not idempotent. | ||
580 | 268 | |||
581 | 269 | |||
582 | 270 | .. _cli_status: | ||
583 | 271 | |||
584 | 272 | status | ||
585 | 273 | ====== | ||
586 | 274 | |||
587 | 275 | Report whether cloud-init is running, done, disabled or errored. Exits | ||
588 | 276 | non-zero if an error is detected in cloud-init. | ||
589 | 277 | |||
590 | 278 | * *\\-\\-long*: detailed status information | ||
591 | 279 | * *\\-\\-wait*: block until cloud-init completes | ||
592 | 280 | |||
593 | 281 | Below are examples of output when cloud-init is running, showing status and | ||
594 | 282 | the currently running modules, as well as when it is done. | ||
595 | 283 | |||
596 | 284 | .. code-block:: shell-session | ||
597 | 285 | |||
598 | 286 | $ cloud-init status | ||
599 | 287 | status: running | ||
600 | 288 | |||
601 | 289 | $ cloud-init status --long | ||
602 | 290 | status: running | ||
603 | 291 | time: Fri, 26 Jan 2018 21:39:43 +0000 | ||
604 | 292 | detail: | ||
605 | 293 | Running in stage: init-local | ||
606 | 294 | |||
607 | 295 | $ cloud-init status | ||
608 | 296 | status: done | ||
609 | 297 | |||
610 | 298 | $ cloud-init status --long | ||
611 | 299 | status: done | ||
612 | 300 | time: Wed, 17 Jan 2018 20:41:59 +0000 | ||
613 | 301 | detail: | ||
614 | 302 | DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] | ||
615 | 303 | |||
616 | 304 | .. vi: textwidth=79 |
PASSED: Continuous integration, rev:c62f9629929 3afcae0dab000a1 888aaf1016d900 /jenkins. ubuntu. com/server/ job/cloud- init-ci/ 1128/
https:/
Executed test runs:
SUCCESS: Checkout
SUCCESS: Unit & Style Tests
SUCCESS: Ubuntu LTS: Build
SUCCESS: Ubuntu LTS: Integration
IN_PROGRESS: Declarative: Post Actions
Click here to trigger a rebuild: /jenkins. ubuntu. com/server/ job/cloud- init-ci/ 1128//rebuild
https:/