diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst index b904eaf4c12..e06637607f7 100644 --- a/doc/rtd/topics/boot.rst +++ b/doc/rtd/topics/boot.rst @@ -158,7 +158,7 @@ scripts until cloud-init is done without having to write your own systemd units dependency chains. See :ref:`cli_status` for more info. First Boot Determination -************************ +======================== cloud-init has to determine whether or not the current boot is the first boot of a new instance or not, so that it applies the appropriate configuration. On diff --git a/doc/rtd/topics/docs.rst b/doc/rtd/topics/docs.rst index 1b15377ec9f..99c2c1402ee 100644 --- a/doc/rtd/topics/docs.rst +++ b/doc/rtd/topics/docs.rst @@ -58,14 +58,6 @@ other pages. For example for the FAQ page this would be: .. _faq: -Footer ------- -The footer should include the textwidth - -.. code-block:: rst - - .. vi: textwidth=79 - Vertical Whitespace ------------------- One newline between each section helps ensure readability of the documentation diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst index 6d790b056d7..f348105fc97 100644 --- a/doc/rtd/topics/format.rst +++ b/doc/rtd/topics/format.rst @@ -7,6 +7,67 @@ User-Data Formats User data that will be acted upon by cloud-init must be in one of the following types. +Cloud Config Data +================= + +Cloud-config is the simplest way to accomplish some things via user-data. Using +cloud-config syntax, the user can specify certain things in a human friendly +format. + +These things include: + +- apt upgrade should be run on first boot +- a different apt mirror should be used +- additional apt sources should be added +- certain SSH keys should be imported +- *and many more...* + +.. note:: + This file must be valid YAML syntax. + +See the :ref:`yaml_examples` section for a commented set of examples of +supported cloud config formats. + +Begins with: ``#cloud-config`` or ``Content-Type: text/cloud-config`` when +using a MIME archive. + +.. note:: + New in cloud-init v. 18.4: Cloud config data can also render cloud instance + metadata variables using jinja templating. See + :ref:`instance_metadata` for more information. + +User-Data Script +================ + +Typically used by those who just want to execute a shell script. + +Begins with: ``#!`` or ``Content-Type: text/x-shellscript`` when using a MIME +archive. + +.. note:: + New in cloud-init v. 18.4: User-data scripts can also render cloud instance + metadata variables using jinja templating. See + :ref:`instance_metadata` for more information. + +Example +------- + +.. code-block:: shell-session + + $ cat myscript.sh + + #!/bin/sh + echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt + + $ euca-run-instances --key mykey --user-data-file myscript.sh ami-a07d95c9 + +Kernel Command Line +=================== + +When using the :ref:`datasource_nocloud` datasource, users can pass user data +via the kernel command line parameters. See the :ref:`datasource_nocloud` +datasource documentation for more details. + Gzip Compressed Content ======================= @@ -39,7 +100,6 @@ Supported content-types are listed from the cloud-init subcommand make-mime: x-include-url x-shellscript - Helper subcommand to generate mime messages ------------------------------------------- @@ -57,32 +117,6 @@ to store the multipart message in ``user-data``: .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py - -User-Data Script -================ - -Typically used by those who just want to execute a shell script. - -Begins with: ``#!`` or ``Content-Type: text/x-shellscript`` when using a MIME -archive. - -.. note:: - New in cloud-init v. 18.4: User-data scripts can also render cloud instance - metadata variables using jinja templating. See - :ref:`instance_metadata` for more information. - -Example -------- - -.. code-block:: shell-session - - $ cat myscript.sh - - #!/bin/sh - echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt - - $ euca-run-instances --key mykey --user-data-file myscript.sh ami-a07d95c9 - Include File ============ @@ -96,44 +130,6 @@ an error occurs reading a file the remaining files will not be read. Begins with: ``#include`` or ``Content-Type: text/x-include-url`` when using a MIME archive. -Cloud Config Data -================= - -Cloud-config is the simplest way to accomplish some things via user-data. Using -cloud-config syntax, the user can specify certain things in a human friendly -format. - -These things include: - -- apt upgrade should be run on first boot -- a different apt mirror should be used -- additional apt sources should be added -- certain SSH keys should be imported -- *and many more...* - -.. note:: - This file must be valid YAML syntax. - -See the :ref:`yaml_examples` section for a commented set of examples of -supported cloud config formats. - -Begins with: ``#cloud-config`` or ``Content-Type: text/cloud-config`` when -using a MIME archive. - -.. note:: - New in cloud-init v. 18.4: Cloud config data can also render cloud instance - metadata variables using jinja templating. See - :ref:`instance_metadata` for more information. - -Upstart Job -=========== - -Content is placed into a file in ``/etc/init``, and will be consumed by upstart -as any other upstart job. - -Begins with: ``#upstart-job`` or ``Content-Type: text/upstart-job`` when using -a MIME archive. - Cloud Boothook ============== @@ -191,12 +187,14 @@ Example Also this `blog`_ post offers another example for more advanced usage. -Kernel Command Line -=================== +Upstart Job +=========== -When using the :ref:`datasource_nocloud` datasource, users can pass user data -via the kernel command line parameters. See the :ref:`datasource_nocloud` -datasource documentation for more details. +Content is placed into a file in ``/etc/init``, and will be consumed by upstart +as any other upstart job. + +Begins with: ``#upstart-job`` or ``Content-Type: text/upstart-job`` when using +a MIME archive. Disabling User-Data =================== @@ -208,5 +206,3 @@ cloud-init from processing user-data. .. [#] See your cloud provider for applicable user-data size limitations... .. _blog: http://foss-boss.blogspot.com/2011/01/advanced-cloud-init-custom-handlers.html - -.. vi: textwidth=79