[docs]: Overhaul user data formats page
holmanb opened this issue · comments
Cloud-init supports multiple formats, which are described on the user data formats page.
This page has a few improvements that should be made:
- Each format deserves a very brief example. This will make our format page more readable and allows skimming and reader intuition to fill in details faster than reading a wall of text.
- This page contains an unrelated kernel command line section. This section does not describe a format, and should be relocated or (more likely) deleted.
- This page contains an unrelated how to disable user data section. This section does not describe a format, and should be relocated.
- This page contains a how to write your own part-handler section. Future plans for this section have already been described in another issue. tl;dr - this belongs elsewhere
- Jinja templated user data is not documented on this page (it is best described on the instance metadata page)
- Currently these formats are not categorized, but could be categorized to make them easier to skim / grok by the reader (see the next section).
Recommended format categorization
These formats fall into two categories, which I will call base formats and meta-formats for now.
Base formats are formats that allow the user to configure the instance via cloud-init. Meta formats are formats that modify or aggregate base formats.
Base formats include the following: cloud config data, user data scripts, cloud-boothooks
Meta formats include the following: include files, gzip compressed content, mime archives, jinja templates (need to be documented)
The User Data Scripts section should additionally:
- Remove
euca-run-instancesreference - Provide info on run frequency
- Include jinja templating in an example to show how that may be used in shell scripts