Skip to content

Commit

Permalink
docs: split example page into example library (#5645)
Browse files Browse the repository at this point in the history
*What does it do?*
Create a single library of yaml examples. There are currently
examples in three places:
- the modules page
- doc/examples
- the yaml examples page

Here I collect ALL existing examples into a single "example library".
The yaml examples page is now a landing page/directory.

* Examples grouped (roughly) by operation or function.
* Standardised formatting across pages.
* Links to relevant module(s) included on all pages.
* Comments extracted from yaml files for better formatting.

Note: not all examples have descriptive titles or explanations
(yet). To be addressed in future work.

*Why is this done?*
* Improved module discoverability/usability for newer users.
* Streamlining.
  - We can now remove examples from the modules page, instead linking to
    relevant examples in the library. We can then remove tabs on the module
    page, to facilitate use of ctrl+f searching for long-time users.
  - We can remove the examples from `doc/examples`, so that examples are
    all in a single place.
  • Loading branch information
s-makin authored Oct 16, 2024
1 parent 1fc063a commit 5819c94
Show file tree
Hide file tree
Showing 70 changed files with 3,196 additions and 12 deletions.
7 changes: 1 addition & 6 deletions doc/module-docs/cc_users_groups/example3.yaml
Original file line number Diff line number Diff line change
@@ -1,9 +1,4 @@
#cloud-config
users:
- gecos: Big Stuff
groups: users, admin
lock_passwd: true
name: newsuper
- name: newsuper
shell: /bin/bash
ssh_import_id: ['lp:falcojr', 'gh:TheRealFalcon']
sudo: ALL=(ALL) NOPASSWD:ALL
5 changes: 1 addition & 4 deletions doc/module-docs/cc_users_groups/example4.yaml
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
#cloud-config
users:
- doas: [permit nopass newsuper, deny newsuper as root]
gecos: Big Stuff
groups: users, admin
lock_passwd: true
name: newsuper
ssh_import_id: ['lp:falcojr', 'gh:TheRealFalcon']

141 changes: 141 additions & 0 deletions doc/rtd/explanation/about-cloud-config.rst
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions doc/rtd/explanation/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 8 additions & 2 deletions doc/rtd/reference/examples.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
.. _yaml_examples:

Cloud config examples
*********************
All cloud config examples
*************************

.. note::
This page is a summary containing all the cloud config YAML examples
together. If you would like to explore examples by operation or process
instead, refer to the :ref:`examples library <examples_library>`.

Including users and groups
==========================
Expand Down Expand Up @@ -150,3 +155,4 @@ Create partitions and filesystems
.. _chef: http://www.chef.io/chef/
.. _puppet: http://puppetlabs.com/
.. _ansible: https://docs.ansible.com/ansible/latest/

59 changes: 59 additions & 0 deletions doc/rtd/reference/examples_library.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
.. _examples_library:

Cloud config examples library
*****************************

.. note::
This page is an index to all the cloud config YAML examples, organised by
operation or process. If you prefer to use a single-page summary containing
every cloud config yaml example, refer to the
:ref:`all examples page <yaml_examples>`.

.. include:: yaml_examples/index_boot.rst
:end-before: .. TOC

.. include:: yaml_examples/index_security.rst
:end-before: .. TOC

.. include:: yaml_examples/index_fs.rst
:end-before: .. TOC

.. include:: yaml_examples/index_users.rst
:end-before: .. TOC

.. include:: yaml_examples/index_hostname.rst
:end-before: .. TOC

.. include:: yaml_examples/index_network.rst
:end-before: .. TOC

.. include:: yaml_examples/index_packages.rst
:end-before: .. TOC

.. include:: yaml_examples/index_logging.rst
:end-before: .. TOC

.. include:: yaml_examples/index_config_manager.rst
:end-before: .. TOC

.. include:: yaml_examples/index_distro.rst
:end-before: .. TOC

.. include:: yaml_examples/index_misc.rst
:end-before: .. TOC

.. toctree::
:hidden:
:titlesonly:

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
1 change: 1 addition & 0 deletions doc/rtd/reference/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ matrices and so on.

modules.rst
examples.rst
examples_library.rst
cli.rst
availability.rst
faq.rst
Expand Down
54 changes: 54 additions & 0 deletions doc/rtd/reference/yaml_examples/ansible.rst
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 5819c94

Please sign in to comment.