canonical · s-makin · Aug 29, 2024 · Sep 20, 2024 · Sep 20, 2024 · Sep 20, 2024
diff --git a/doc/rtd/explanation/about-cloud-config.rst b/doc/rtd/explanation/about-cloud-config.rst
@@ -0,0 +1,141 @@
+.. _about-cloud-config:
+
+About the cloud-config file
+***************************
+
+The ``#cloud-config`` file is a type of user data that cloud-init can consume
+to automatically set up various aspects of the system. It is commonly referred
+to as **cloud config**. Using cloud config to configure your machine leverages
+the best practices encoded into cloud-init's modules in a distribution-agnostic
+way.
+
+Note that networks are not configurable via the ``#cloud-config`` file because
+:ref:`network configuration <network_config>` comes from the cloud.
+
+How do I create a cloud-config file?
+====================================
+
+The cloud-config file uses `YAML version 1.1`_. The file is composed of a
+**header** and one or more **modules**.
+
+* **The header**:
+  The first line **must start** with ``#cloud-config``. This line identifies
+  the file to cloud-init and ensures that it will be processed as intended.
+
+* **The modules**:
+  After the header, every aspect of the system's configuration is controlled
+  through specific cloud-init modules.
+
+Most modules are specified through the use of one or more **top-level keys**,
+and the configuration options are set using YAML key-value pairs or list types,
+according to the config schema. It follows this general format:
+
+.. code-block:: yaml
+
+   #cloud-config
+   top-level-key:
+     config-key-1: config-value-1
+     config-key-2: config-value-2
+     list-type:
+     - list-value-1
+       additional-list-value-1
+     - list-value-2
+
+The order of the top-level keys is unimportant -- they can be written in any
+order, and cloud-init handles the order of operations.
+
+Let us consider a real example using the :ref:`Keyboard <mod_cc_keyboard>`
+module. The top-level key for this module is ``keyboard:``, and beneath that
+are the various configuration options for the module shown as key-value pairs:
+
+.. code-block:: yaml
+
+   #cloud-config
+   keyboard:
+     layout: us
+     model: pc105
+     variant: nodeadkeys
+     options: compose:rwin
+
+Not all modules require a top-level key, and will run on the system anyway if
+certain conditions are met. A full list of modules can be found
+:ref:`on our modules page <modules>`. This list also shows the valid schema for
+every module, and simple YAML examples.
+
+Checking your cloud-config file
+===============================
+
+Once you have constructed your cloud-config file, you can check it against
+the :ref:`cloud-config validation tool <check_user_data_cloud_config>`. This
+tool tests the YAML in your file against the cloud-init schema and will warn
+you of any errors.
+
+Example cloud-config file
+=========================
+
+The following code is an example of a complete user data cloud-config file.
+The :ref:`cloud-config example library <yaml_examples>` contains further
+examples that can be copy/pasted and adapted to your needs.
+
+.. code-block:: yaml
+
+   #cloud-config
+
+   # Basic system setup
+   hostname: example-host
+   fqdn: example-host.example.com
+
+   # User setup configuration
+   users:
+     - name: exampleuser
+       gecos: Example User
+       sudo: ['ALL=(ALL) NOPASSWD:ALL']
+       groups: sudo
+       homedir: /home/exampleuser
+       shell: /bin/bash
+       ssh_authorized_keys:
+         - ssh-rsa AAAAB3...restofpublickey user@host
+
+   # Change passwords for exampleuser using chpasswd
+   chpasswd:
+     expire: false
+     users:
+     - {name: exampleuser, password: terriblepassword12345, type: text}
+
+   # Package management
+   package_update: true
+   package_upgrade: true
+   packages:
+     - git
+     - nginx
+     - python3
+
+   # Commands to run at the end of the cloud-init process
+   runcmd:
+     - echo "Hello, world!" > /etc/motd
+     - systemctl restart nginx
+     - mkdir -p /var/www/html
+     - echo "<html><body><h1>Welcome to the party, pal!</h1></body></html>" > /var/www/html/index.html
+
+   # Write files to the instance
+   write_files:
+     - path: /etc/example_config.conf
+       content: |
+         [example-config]
+         key=value
+     - path: /etc/motd
+       content: |
+         Some text that will appear in your MOTD!
+
+   # Final message, shown after cloud-init completes
+   final_message: "The system is up, after $UPTIME seconds"
+
+   # Reboot the instance after configuration
+   power_state:
+     mode: reboot
+     message: Rebooting after initial setup
+     timeout: 30
+     condition: True
+
+.. LINKS
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html
diff --git a/doc/rtd/explanation/index.rst b/doc/rtd/explanation/index.rst
@@ -12,6 +12,7 @@ knowledge and become better at using and configuring ``cloud-init``.
 
    introduction.rst
    format.rst
+   about-cloud-config.rst
    configuration.rst
    boot.rst
    first_boot.rst

diff --git a/doc/rtd/reference/examples.rst b/doc/rtd/reference/examples.rst
@@ -1,152 +1,53 @@
 .. _yaml_examples:
 
-Cloud config examples
-*********************
+Cloud config examples library
+*****************************
 
-Including users and groups
-==========================
+.. include:: yaml_examples/index_boot.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-user-groups.txt
-   :language: yaml
-   :linenos:
+.. include:: yaml_examples/index_security.rst
+   :end-before: .. TOC
 
-Writing out arbitrary files
-===========================
+.. include:: yaml_examples/index_fs.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-write-files.txt
-   :language: yaml
-   :linenos:
+.. include:: yaml_examples/index_users.rst
+   :end-before: .. TOC
 
-Adding a yum repository
-=======================
+.. include:: yaml_examples/index_hostname.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-yum-repo.txt
-   :language: yaml
-   :linenos:
+.. include:: yaml_examples/index_network.rst
+   :end-before: .. TOC
 
-Configure an instance's trusted CA certificates
-===============================================
+.. include:: yaml_examples/index_packages.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-ca-certs.txt
-   :language: yaml
-   :linenos:
+.. include:: yaml_examples/index_logging.rst
+   :end-before: .. TOC
 
-Install and run `chef`_ recipes
-===============================
+.. include:: yaml_examples/index_config_manager.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-chef.txt
-   :language: yaml
-   :linenos:
+.. include:: yaml_examples/index_distro.rst
+   :end-before: .. TOC
 
-Install and run `ansible-pull`
-===============================
+.. include:: yaml_examples/index_misc.rst
+   :end-before: .. TOC
 
-.. literalinclude:: ../../examples/cloud-config-ansible-pull.txt
-   :language: yaml
-   :linenos:
+.. toctree::
+    :hidden:
+    :titlesonly:
 
-Configure instance to be managed by Ansible
-===========================================
-
-.. literalinclude:: ../../examples/cloud-config-ansible-managed.txt
-   :language: yaml
-   :linenos:
-
-Configure instance to be an Ansible controller
-==============================================
-
-.. literalinclude:: ../../examples/cloud-config-ansible-controller.txt
-   :language: yaml
-   :linenos:
-
-Add primary apt repositories
-============================
-
-.. literalinclude:: ../../examples/cloud-config-add-apt-repos.txt
-   :language: yaml
-   :linenos:
-
-Run commands on first boot
-==========================
-
-.. literalinclude:: ../../examples/cloud-config-boot-cmds.txt
-   :language: yaml
-   :linenos:
-
-.. literalinclude:: ../../examples/cloud-config-run-cmds.txt
-   :language: yaml
-   :linenos:
-
-Run commands on very early at every boot
-========================================
-
-.. literalinclude:: ../../examples/boothook.txt
-   :language: bash
-   :linenos:
-
-Install arbitrary packages
-==========================
-
-.. literalinclude:: ../../examples/cloud-config-install-packages.txt
-   :language: yaml
-   :linenos:
-
-Update apt database on first boot
-=================================
-
-.. literalinclude:: ../../examples/cloud-config-update-apt.txt
-   :language: yaml
-   :linenos:
-
-Run apt or yum upgrade
-======================
-
-.. literalinclude:: ../../examples/cloud-config-update-packages.txt
-   :language: yaml
-   :linenos:
-
-Adjust mount points mounted
-===========================
-
-.. literalinclude:: ../../examples/cloud-config-mount-points.txt
-   :language: yaml
-   :linenos:
-
-``Configure instance's SSH keys``
-=================================
-
-.. literalinclude:: ../../examples/cloud-config-ssh-keys.txt
-   :language: yaml
-   :linenos:
-
-Additional apt configuration and repositories
-=============================================
-
-.. literalinclude:: ../../examples/cloud-config-apt.txt
-    :language: yaml
-    :linenos:
-
-Disk setup
-==========
-
-.. literalinclude:: ../../examples/cloud-config-disk-setup.txt
-    :language: yaml
-    :linenos:
-
-Configure data sources
-======================
-
-.. literalinclude:: ../../examples/cloud-config-datasources.txt
-   :language: yaml
-   :linenos:
-
-Create partitions and filesystems
-=================================
-
-.. literalinclude:: ../../examples/cloud-config-disk-setup.txt
-   :language: yaml
-   :linenos:
-
-.. _chef: http://www.chef.io/chef/
-.. _puppet: http://puppetlabs.com/
-.. _ansible: https://docs.ansible.com/ansible/latest/
+    yaml_examples/index_boot
+    yaml_examples/index_security
+    yaml_examples/index_fs
+    yaml_examples/index_users
+    yaml_examples/index_hostname
+    yaml_examples/index_network
+    yaml_examples/index_packages
+    yaml_examples/index_logging
+    yaml_examples/index_config_manager
+    yaml_examples/index_distro
+    yaml_examples/index_misc
diff --git a/doc/rtd/reference/yaml_examples/ansible.rst b/doc/rtd/reference/yaml_examples/ansible.rst
@@ -0,0 +1,54 @@
+.. _cce-ansible:
+
+Install Ansible
+***************
+
+These examples show how to achieve a basic installation of Ansible, and
+configures the location that playbooks should be pulled from.
+
+For a full list of keys, refer to the :ref:`Ansible module <mod_cc_ansible>`
+schema.
+
+Install via package manager
+===========================
+
+This example will use the operating system distribution's package manager to
+install Ansible.
+
+.. literalinclude:: ../../../module-docs/cc_ansible/example1.yaml
+   :language: yaml
+   :linenos:
+
+Install via pip
+===============
+
+This example uses the Python package manager ``pip`` to install Ansible.
+
+.. literalinclude:: ../../../module-docs/cc_ansible/example2.yaml
+   :language: yaml
+   :linenos:
+
+Install and run Ansible pull
+============================
+
+If you're already installing other packages, you may want to manually install
+Ansible to avoid multiple calls to your package manager. This example shows
+how to install Ansible using ``pip`` and run the ``ubuntu.yml`` playbook,
+pulled from a specific git repository.
+
+For a full list of keys, refer to the :ref:`Ansible module <mod_cc_ansible>`
+schema.
+
+.. code-block:: yaml
+
+    #cloud-config
+    package_update: true
+    package_upgrade: true
+    packages:
+      - git
+    ansible:
+      install_method: pip
+      pull:
+        url: "https://github.com/holmanb/vmboot.git"
+        playbook_name: ubuntu.yml
+