From 63e57c177e0f86b41108aedfea3e6ac71186ab18 Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Thu, 29 Aug 2024 11:19:53 +0100 Subject: [PATCH 01/11] Add examples as separate pages --- doc/rtd/explanation/about-cloud-config.rst | 85 ++++ doc/rtd/explanation/index.rst | 1 + doc/rtd/reference/examples.rst | 175 ++------- doc/rtd/reference/yaml_examples/ansible.rst | 54 +++ .../yaml_examples/ansible_controller.rst | 168 ++++++++ .../yaml_examples/ansible_managed.rst | 69 ++++ doc/rtd/reference/yaml_examples/apk_repo.rst | 37 ++ doc/rtd/reference/yaml_examples/apt.rst | 369 ++++++++++++++++++ .../reference/yaml_examples/apt_pipeline.rst | 35 ++ doc/rtd/reference/yaml_examples/apt_repos.rst | 78 ++++ doc/rtd/reference/yaml_examples/archive.rst | 20 + .../yaml_examples/archive_launch_index.rst | 33 ++ doc/rtd/reference/yaml_examples/boot_cmds.rst | 50 +++ doc/rtd/reference/yaml_examples/byobu.rst | 22 ++ doc/rtd/reference/yaml_examples/ca_certs.rst | 52 +++ doc/rtd/reference/yaml_examples/chef.rst | 179 +++++++++ .../reference/yaml_examples/datasources.rst | 95 +++++ .../yaml_examples/disable_ec2_metadata.rst | 15 + .../reference/yaml_examples/disk_setup.rst | 324 +++++++++++++++ doc/rtd/reference/yaml_examples/fan.rst | 14 + .../reference/yaml_examples/final_message.rst | 18 + doc/rtd/reference/yaml_examples/gluster.rst | 22 ++ doc/rtd/reference/yaml_examples/growpart.rst | 22 ++ doc/rtd/reference/yaml_examples/grub_dpkg.rst | 12 + .../reference/yaml_examples/index_boot.rst | 36 ++ .../yaml_examples/index_config_manager.rst | 34 ++ .../reference/yaml_examples/index_distro.rst | 25 ++ doc/rtd/reference/yaml_examples/index_fs.rst | 23 ++ .../yaml_examples/index_hostname.rst | 14 + .../reference/yaml_examples/index_logging.rst | 16 + .../reference/yaml_examples/index_misc.rst | 32 ++ .../reference/yaml_examples/index_network.rst | 20 + .../yaml_examples/index_packages.rst | 28 ++ .../yaml_examples/index_security.rst | 22 ++ .../reference/yaml_examples/index_users.rst | 14 + .../yaml_examples/install_hotplug.rst | 25 ++ doc/rtd/reference/yaml_examples/keyboard.rst | 36 ++ .../yaml_examples/keys_to_console.rst | 33 ++ doc/rtd/reference/yaml_examples/landscape.rst | 37 ++ .../reference/yaml_examples/launch_index.rst | 19 + .../yaml_examples/locale_and_timezone.rst | 37 ++ doc/rtd/reference/yaml_examples/lxd.rst | 58 +++ .../reference/yaml_examples/mcollective.rst | 23 ++ doc/rtd/reference/yaml_examples/mounts.rst | 107 +++++ doc/rtd/reference/yaml_examples/ntp.rst | 66 ++++ .../reference/yaml_examples/phone_home.rst | 22 ++ .../yaml_examples/power_state_change.rst | 25 ++ doc/rtd/reference/yaml_examples/puppet.rst | 22 ++ .../yaml_examples/redhat_subscription.rst | 29 ++ doc/rtd/reference/yaml_examples/reporting.rst | 21 + doc/rtd/reference/yaml_examples/resizefs.rst | 27 ++ .../reference/yaml_examples/resolv_conf.rst | 19 + doc/rtd/reference/yaml_examples/rsyslog.rst | 31 ++ .../reference/yaml_examples/salt_minion.rst | 12 + doc/rtd/reference/yaml_examples/scripts.rst | 80 ++++ .../reference/yaml_examples/seed_random.rst | 25 ++ .../reference/yaml_examples/set_hostname.rst | 34 ++ .../reference/yaml_examples/set_passwords.rst | 34 ++ doc/rtd/reference/yaml_examples/snap.rst | 42 ++ doc/rtd/reference/yaml_examples/spacewalk.rst | 17 + doc/rtd/reference/yaml_examples/ssh.rst | 55 +++ .../ssh_authkey_fingerprints.rst | 31 ++ .../reference/yaml_examples/ssh_import_id.rst | 19 + .../yaml_examples/ubuntu_drivers.rst | 15 + .../reference/yaml_examples/ubuntu_pro.rst | 89 +++++ .../yaml_examples/update_etc_hosts.rst | 53 +++ .../yaml_examples/update_hostname.rst | 67 ++++ .../yaml_examples/update_upgrade.rst | 35 ++ .../reference/yaml_examples/user_groups.rst | 255 ++++++++++++ doc/rtd/reference/yaml_examples/wireguard.rst | 25 ++ .../reference/yaml_examples/write_files.rst | 54 +++ doc/rtd/reference/yaml_examples/yum_repo.rst | 59 +++ .../reference/yaml_examples/zypper_repo.rst | 13 + 73 files changed, 3727 insertions(+), 137 deletions(-) create mode 100644 doc/rtd/explanation/about-cloud-config.rst create mode 100644 doc/rtd/reference/yaml_examples/ansible.rst create mode 100644 doc/rtd/reference/yaml_examples/ansible_controller.rst create mode 100644 doc/rtd/reference/yaml_examples/ansible_managed.rst create mode 100644 doc/rtd/reference/yaml_examples/apk_repo.rst create mode 100644 doc/rtd/reference/yaml_examples/apt.rst create mode 100644 doc/rtd/reference/yaml_examples/apt_pipeline.rst create mode 100644 doc/rtd/reference/yaml_examples/apt_repos.rst create mode 100644 doc/rtd/reference/yaml_examples/archive.rst create mode 100644 doc/rtd/reference/yaml_examples/archive_launch_index.rst create mode 100644 doc/rtd/reference/yaml_examples/boot_cmds.rst create mode 100644 doc/rtd/reference/yaml_examples/byobu.rst create mode 100644 doc/rtd/reference/yaml_examples/ca_certs.rst create mode 100644 doc/rtd/reference/yaml_examples/chef.rst create mode 100644 doc/rtd/reference/yaml_examples/datasources.rst create mode 100644 doc/rtd/reference/yaml_examples/disable_ec2_metadata.rst create mode 100644 doc/rtd/reference/yaml_examples/disk_setup.rst create mode 100644 doc/rtd/reference/yaml_examples/fan.rst create mode 100644 doc/rtd/reference/yaml_examples/final_message.rst create mode 100644 doc/rtd/reference/yaml_examples/gluster.rst create mode 100644 doc/rtd/reference/yaml_examples/growpart.rst create mode 100644 doc/rtd/reference/yaml_examples/grub_dpkg.rst create mode 100644 doc/rtd/reference/yaml_examples/index_boot.rst create mode 100644 doc/rtd/reference/yaml_examples/index_config_manager.rst create mode 100644 doc/rtd/reference/yaml_examples/index_distro.rst create mode 100644 doc/rtd/reference/yaml_examples/index_fs.rst create mode 100644 doc/rtd/reference/yaml_examples/index_hostname.rst create mode 100644 doc/rtd/reference/yaml_examples/index_logging.rst create mode 100644 doc/rtd/reference/yaml_examples/index_misc.rst create mode 100644 doc/rtd/reference/yaml_examples/index_network.rst create mode 100644 doc/rtd/reference/yaml_examples/index_packages.rst create mode 100644 doc/rtd/reference/yaml_examples/index_security.rst create mode 100644 doc/rtd/reference/yaml_examples/index_users.rst create mode 100644 doc/rtd/reference/yaml_examples/install_hotplug.rst create mode 100644 doc/rtd/reference/yaml_examples/keyboard.rst create mode 100644 doc/rtd/reference/yaml_examples/keys_to_console.rst create mode 100644 doc/rtd/reference/yaml_examples/landscape.rst create mode 100644 doc/rtd/reference/yaml_examples/launch_index.rst create mode 100644 doc/rtd/reference/yaml_examples/locale_and_timezone.rst create mode 100644 doc/rtd/reference/yaml_examples/lxd.rst create mode 100644 doc/rtd/reference/yaml_examples/mcollective.rst create mode 100644 doc/rtd/reference/yaml_examples/mounts.rst create mode 100644 doc/rtd/reference/yaml_examples/ntp.rst create mode 100644 doc/rtd/reference/yaml_examples/phone_home.rst create mode 100644 doc/rtd/reference/yaml_examples/power_state_change.rst create mode 100644 doc/rtd/reference/yaml_examples/puppet.rst create mode 100644 doc/rtd/reference/yaml_examples/redhat_subscription.rst create mode 100644 doc/rtd/reference/yaml_examples/reporting.rst create mode 100644 doc/rtd/reference/yaml_examples/resizefs.rst create mode 100644 doc/rtd/reference/yaml_examples/resolv_conf.rst create mode 100644 doc/rtd/reference/yaml_examples/rsyslog.rst create mode 100644 doc/rtd/reference/yaml_examples/salt_minion.rst create mode 100644 doc/rtd/reference/yaml_examples/scripts.rst create mode 100644 doc/rtd/reference/yaml_examples/seed_random.rst create mode 100644 doc/rtd/reference/yaml_examples/set_hostname.rst create mode 100644 doc/rtd/reference/yaml_examples/set_passwords.rst create mode 100644 doc/rtd/reference/yaml_examples/snap.rst create mode 100644 doc/rtd/reference/yaml_examples/spacewalk.rst create mode 100644 doc/rtd/reference/yaml_examples/ssh.rst create mode 100644 doc/rtd/reference/yaml_examples/ssh_authkey_fingerprints.rst create mode 100644 doc/rtd/reference/yaml_examples/ssh_import_id.rst create mode 100644 doc/rtd/reference/yaml_examples/ubuntu_drivers.rst create mode 100644 doc/rtd/reference/yaml_examples/ubuntu_pro.rst create mode 100644 doc/rtd/reference/yaml_examples/update_etc_hosts.rst create mode 100644 doc/rtd/reference/yaml_examples/update_hostname.rst create mode 100644 doc/rtd/reference/yaml_examples/update_upgrade.rst create mode 100644 doc/rtd/reference/yaml_examples/user_groups.rst create mode 100644 doc/rtd/reference/yaml_examples/wireguard.rst create mode 100644 doc/rtd/reference/yaml_examples/write_files.rst create mode 100644 doc/rtd/reference/yaml_examples/yum_repo.rst create mode 100644 doc/rtd/reference/yaml_examples/zypper_repo.rst diff --git a/doc/rtd/explanation/about-cloud-config.rst b/doc/rtd/explanation/about-cloud-config.rst new file mode 100644 index 00000000000..948e4884f15 --- /dev/null +++ b/doc/rtd/explanation/about-cloud-config.rst @@ -0,0 +1,85 @@ +.. _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 overrides all other types of user data, so if there is a conflict between +the config you specify in other :ref:`user data formats `, +the contents of the ``#cloud-config`` file will take precendence. + +Note that networks are not configurable via the ``#cloud-config`` file because +:ref:`network configuration ` occurs before user data is +consumed and applied. + +How do I create a cloud-config file? +==================================== + +The cloud-config file can be written in any valid YAML but 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. + +After the first line, every aspect of the system's configuration is controlled +through specific cloud-init **modules**. Each module included in the +``cloud-config`` file can be thought of as a section. + +Let us consider the example of the "keyboard" module. The module has a +corresponding top-level key (``keyboard:``, in this case), and beneath that +the various configuration parameters are defined: + +.. code-block:: yaml + + keyboard: + layout: us + model: pc105 + variant: nodeadkeys + options: compose:rwin + +A full list of modules can be found :ref:`on our modules page `. This +list also shows the valid schema keys for every module, and YAML examples. + +Module ordering +--------------- + +The order of the different module "sections" is mostly unimportant and modules +can be shown in any order -- except where there are dependencies. For example, +if you want to create users and also put them in a specific group, then the +``groups`` section must go before ``users`` so that the groups are created +first. + +Cloud-config for the live installer +----------------------------------- + +For the special case where your cloud-config file is will be consumed by the +Ubuntu installer, you will need to include the the ``autoinstall:`` +top level key. The presence of this key will instruct cloud-init not to process +the user-data itself, but instead to pass it directly to the installer for +processing. + +For more detailed instructions for this case, refer to the installer +documentation on using `cloud-init with the autoinstaller`_. + +Checking your cloud-config file +=============================== + +Once you have constructed your cloud-config file, you can check it against +the :ref:`cloud-config validation tool `. 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 working user data cloud-config file. +The :ref:`cloud-config example library ` contains further +examples that can be copy/pasted and adapted to your needs. + +.. code-block:: yaml + + #cloud-config + + +.. LINKS +.. _cloud-init with the autoinstaller: https://canonical-subiquity.readthedocs-hosted.com/en/latest/tutorial/providing-autoinstall.html#autoinstall-by-way-of-cloud-config diff --git a/doc/rtd/explanation/index.rst b/doc/rtd/explanation/index.rst index 8a1adc4639e..9e2b82a790d 100644 --- 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 index fe2703031ac..e2b2167f773 100644 --- 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 new file mode 100644 index 00000000000..fe0a9ce0f23 --- /dev/null +++ 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 ` +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 ` +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 + diff --git a/doc/rtd/reference/yaml_examples/ansible_controller.rst b/doc/rtd/reference/yaml_examples/ansible_controller.rst new file mode 100644 index 00000000000..df9deadc9f5 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/ansible_controller.rst @@ -0,0 +1,168 @@ +.. _cce-ansible-controller: + +Configure instance to be an Ansible controller +********************************************** + +This slightly more complex example demonstrates how to set up an Ansible +controller host on boot. Here we break down each section, with the full and +unbroken config at the end of the page. + +The example installs a playbook repository from a remote private repository +and then runs two of the plays. + +For a full list of keys, refer to the `Ansible module`_ schema. + +Update, upgrade and install packages +==================================== + +.. code-block:: yaml + + #cloud-config + package_update: true + package_upgrade: true + packages: ['git', 'python3-pip'] + +Set up an Ansible user +====================== + +We give the local Ansible user password-less ``sudo`` so that Ansible can +write to a local root-only file. + +.. code-block:: yaml + + users: + - name: ansible + gecos: Ansible User + shell: /bin/bash + groups: users,admin,wheel,lxd + sudo: ALL=(ALL) NOPASSWD:ALL + +Initialize LXD using cloud-init +=============================== + +In our example, a LXD container is started (using Ansible) on boot, so we must +initialize LXD. + +.. code-block:: yaml + + lxd: + init: + storage_backend: dir + +Configure and run Ansible on boot +================================= + +First we install Ansible using ``pip``, and ensure that the +``community.general`` collection is installed (it is likely to be already +installed by ``pip``). + +Then we use a deploy key to clone a remote private repository and run two +playbooks: + +* The first playbook starts a LXD container and creates a new inventory file +* The second playbook connects to and configures the container using Ansible + +The public version of the playbooks can be inspected at this URL: +``https://github.com/holmanb/ansible-lxd-public`` + +.. code-block:: yaml + + ansible: + install_method: pip + package_name: ansible + run_user: ansible + galaxy: + actions: ['ansible-galaxy', 'collection', 'install', 'community.general'] + setup_controller: + repositories: + - path: /home/ansible/my-repo/ + source: git@github.com:holmanb/ansible-lxd-private.git + run_ansible: + - playbook_dir: /home/ansible/my-repo + playbook_name: start-lxd.yml + timeout: 120 + forks: 1 + private_key: /home/ansible/.ssh/id_rsa + - playbook_dir: /home/ansible/my-repo + playbook_name: configure-lxd.yml + become_user: ansible + timeout: 120 + forks: 1 + private_key: /home/ansible/.ssh/id_rsa + inventory: new_ansible_hosts + +Write a deploy key to the filesystem for Ansible +================================================ + +This deploy key is tied to a `private GitHub repository`_. It exists to +demonstrate how deploy keys are used in Ansible. A duplicate public copy of +the repository `exists here`_. + +.. code-block:: yaml + + write_files: + - path: /home/ansible/.ssh/known_hosts + owner: ansible:ansible + permissions: 0o600 + defer: true + content: | + |1|YJEFAk6JjnXpUjUSLFiBQS55W9E=|OLNePOn3eBa1PWhBBmt5kXsbGM4= ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl + |1|PGGnpCpqi0aakERS4BWnYxMkMwM=|Td0piZoS4ZVC0OzeuRwKcH1MusM= ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ== + |1|OJ89KrsNcFTOvoCP/fPGKpyUYFo=|cu7mNzF+QB/5kR0spiYmUJL7DAI= ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg= + - path: /home/ansible/.ssh/id_rsa + owner: ansible:ansible + permissions: 0o600 + defer: true + encoding: base64 + content: | + LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFB + QUFBQkc1dmJtVUFBQUFFYm05dVpRQUFBQUFBQUFBQkFBQUJsd0FBQUFkemMyZ3RjbgpOaEFBQUFB + d0VBQVFBQUFZRUEwUWlRa05WQS9VTEpWZzBzT1Q4TEwyMnRGckg5YVR1SWFNT1FiVFdtWjlNUzJh + VTZ0cDZoClJDYklWSkhmOHdsaGV3MXNvWmphWVVQSFBsUHNISm5UVlhJTnFTTlpEOGF0Rldjd1gy + ZTNBOElZNEhpN0NMMDE3MVBoMVUKYmJGNGVIT1JaVkY2VVkzLzhmbXQ3NmhVYnpiRVhkUXhQdVdh + a0IyemxXNTdFclpOejJhYVdnY2pJUGdHV1RNZWVqbEpOcQpXUW9MNlFzSStpeUlzYXNMc1RTajha + aVgrT1VjanJEMUY4QXNKS3ZWQStKbnVZNUxFeno1TGQ2SGxGc05XVWtoZkJmOWVOClpxRnJCc1Vw + M2VUY1FtejFGaHFFWDJIQjNQT3VSTzlKemVGcTJaRE8wUlNQN09acjBMYm8vSFVTK3V5VkJNTDNi + eEF6dEIKQWM5dFJWZjRqcTJuRjNkcUpwVTFFaXZzR0sxaHJZc0VNQklLK0srVzRwc1F5c3ZTL0ZK + V2lXZmpqWVMwei9IbkV4MkpHbApOUXUrYkMxL1dXSGVXTGFvNGpSckRSZnNIVnVscTE2MElsbnNx + eGl1MmNHd081V29Fc1NHdThucXB5ZzQzWkhDYjBGd21CCml6UFFEQVNsbmlXanFjS21mblRycHpB + eTNlVldhd3dsTnBhUWtpZFRBQUFGZ0dLU2o4ZGlrby9IQUFBQUIzTnphQzF5YzIKRUFBQUdCQU5F + SWtKRFZRUDFDeVZZTkxEay9DeTl0clJheC9XazdpR2pEa0cwMXBtZlRFdG1sT3JhZW9VUW15RlNS + My9NSgpZWHNOYktHWTJtRkR4ejVUN0J5WjAxVnlEYWtqV1EvR3JSVm5NRjludHdQQ0dPQjR1d2k5 + TmU5VDRkVkcyeGVIaHprV1ZSCmVsR04vL0g1cmUrb1ZHODJ4RjNVTVQ3bG1wQWRzNVZ1ZXhLMlRj + OW1tbG9ISXlENEJsa3pIbm81U1RhbGtLQytrTENQb3MKaUxHckM3RTBvL0dZbC9qbEhJNnc5UmZB + TENTcjFRUGlaN21PU3hNOCtTM2VoNVJiRFZsSklYd1gvWGpXYWhhd2JGS2QzawozRUpzOVJZYWhG + OWh3ZHp6cmtUdlNjM2hhdG1RenRFVWorem1hOUMyNlB4MUV2cnNsUVRDOTI4UU03UVFIUGJVVlgr + STZ0CnB4ZDNhaWFWTlJJcjdCaXRZYTJMQkRBU0N2aXZsdUtiRU1yTDB2eFNWb2xuNDQyRXRNL3g1 + eE1kaVJwVFVMdm13dGYxbGgKM2xpMnFPSTBhdzBYN0IxYnBhdGV0Q0paN0tzWXJ0bkJzRHVWcUJM + RWhydko2cWNvT04yUndtOUJjSmdZc3owQXdFcFo0bApvNm5DcG41MDY2Y3dNdDNsVm1zTUpUYVdr + SkluVXdBQUFBTUJBQUVBQUFHQUV1ejc3SHU5RUVaeXVqTE9kVG5BVzlhZlJ2ClhET1pBNnBTN3lX + RXVmanc1Q1NsTUx3aXNSODN5d3cwOXQxUVd5dmhScUV5WW12T0JlY3NYZ2FTVXRuWWZmdFd6NDRh + cHkKL2dRWXZNVkVMR0thSkFDL3E3dmpNcEd5cnhVUGt5TE1oY2tBTFUyS1lnVisvcmovajZwQk1l + VmxjaG1rM3Bpa1lyZmZVWApKRFk5OTBXVk8xOTREbTBidUxSekp2Zk1LWUYyQmNmRjRUdmFyak9Y + V0F4U3VSOHd3dzA1MG9KOEhkS2FoVzdDbTVTMHBvCkZSbk5YRkdNbkxBNjJ2TjAwdkpXOFY3ajd2 + dWk5dWtCYmhqUldhSnVZNXJkRy9VWW16QWU0d3ZkSUVucGs5eEluNkpHQ3AKRlJZVFJuN2xUaDUr + L1FsUTZGWFJQOElyMXZYWkZuaEt6bDBLOFZxaDJzZjRNNzlNc0lVR0FxR3hnOXhkaGpJYTVkbWdw + OApOMThJRURvTkVWS1ViS3VLZS9aNXlmOFo5dG1leGZIMVl0dGptWE1Pb2pCdlVISWpSUzVoZEk5 + TnhuUEdSTFkya2pBemNtCmdWOVJ2M3Z0ZEYvK3phbGszZkFWTGVLOGhYSytkaS83WFR2WXBmSjJF + WkJXaU5yVGVhZ2ZOTkdpWXlkc1F5M3pqWkFBQUEKd0JOUmFrN1VycW5JSE1abjdwa0NUZ2NlYjFN + ZkJ5YUZ0bE56ZCtPYmFoNTRIWUlRajVXZFpUQkFJVFJlTVpOdDlTNU5BUgpNOHNRQjhVb1pQYVZT + QzNwcElMSU9mTGhzNktZajZSckdkaVl3eUloTVBKNWtSV0Y4eEdDTFVYNUNqd0gyRU9xN1hoSVd0 + Ck13RUZ0ZC9nRjJEdTdIVU5GUHNaR256SjNlN3BES0RuRTd3MmtoWjhDSXBURmdENzY5dUJZR0F0 + azQ1UVlURG81SnJvVk0KWlBEcTA4R2IvUmhJZ0pMbUlwTXd5cmVWcExMTGU4U3dvTUpKK3JpaG1u + Slp4TzhnQUFBTUVBMGxoaUtlemVUc2hodDR4dQpyV2MwTnh4RDg0YTI5Z1NHZlRwaERQT3JsS1NF + WWJrU1hoanFDc0FaSGQ4UzhrTXIzaUY2cG9PazNJV1N2Rko2bWJkM2llCnFkUlRnWEg5VGh3azRL + Z3BqVWhOc1F1WVJIQmJJNTlNbytCeFNJMUIxcXptSlNHZG1DQkw1NHd3elptRktEUVBRS1B4aUwK + bjBNbGM3R29vaURNalQxdGJ1Vy9PMUVMNUVxVFJxd2dXUFRLaEJBNnI0UG5HRjE1MGhaUklNb29a + a0Qyelg2YjFzR29qawpRcHZLa0V5a1R3bktDekY1VFhPOCt3SjNxYmNFbzlBQUFBd1FEK1owcjY4 + YzJZTU5wc215ajNaS3RaTlBTdkpOY0xteUQvCmxXb05KcTNkakpONHMySmJLOGw1QVJVZFczeFNG + RURJOXl4L3dwZnNYb2FxV255Z1AzUG9GdzJDTTRpMEVpSml5dnJMRlUKcjNKTGZEVUZSeTNFSjI0 + UnNxYmlnbUVzZ1FPelRsM3hmemVGUGZ4Rm9PaG9rU3ZURzg4UFFqaTFBWUh6NWtBN3A2WmZhegpP + azExckpZSWU3K2U5QjBsaGt1MEFGd0d5cWxXUW1TL01oSXBuakhJazV0UDRoZUhHU216S1FXSkRi + VHNrTldkNmFxMUc3CjZIV2ZEcFg0SGdvTThBQUFBTGFHOXNiV0Z1WWtCaGNtTT0KLS0tLS1FTkQg + T1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCg== + +.. LINKS +.. _Ansible module: https://cloudinit.readthedocs.io/en/latest/reference/modules.html#ansible +.. _private GitHub repository: https://github.com/holmanb/ansible-lxd-private +.. _exists here: https://github.com/holmanb/ansible-lxd-public diff --git a/doc/rtd/reference/yaml_examples/ansible_managed.rst b/doc/rtd/reference/yaml_examples/ansible_managed.rst new file mode 100644 index 00000000000..83eff726c42 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/ansible_managed.rst @@ -0,0 +1,69 @@ +.. _cce-ansible-managed: + +Configure instance to be managed by Ansible +******************************************* + +A common use for cloud-init is to bootstrap user and SSH settings, to be +managed by a remote configuration management tool (such as Ansible). + +This example assumes a default Ubuntu cloud image, which should contain +the required software to be managed remotely by Ansible. + +For a full list of keys, refer to the :ref:`Ansible module ` +schema. + +.. code-block:: yaml + + #cloud-config + ssh_pwauth: false + users: + - name: ansible + gecos: Ansible User + groups: users,admin,wheel + sudo: ALL=(ALL) NOPASSWD:ALL + shell: /bin/bash + lock_passwd: true + ssh_authorized_keys: + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDRCJCQ1UD9QslWDSw5Pwsvba0Wsf1pO4how5BtNaZn0xLZpTq2nqFEJshUkd/zCWF7DWyhmNphQ8c+U+wcmdNVcg2pI1kPxq0VZzBfZ7cDwhjgeLsIvTXvU+HVRtsXh4c5FlUXpRjf/x+a3vqFRvNsRd1DE+5ZqQHbOVbnsStk3PZppaByMg+AZZMx56OUk2pZCgvpCwj6LIixqwuxNKPxmJf45RyOsPUXwCwkq9UD4me5jksTPPkt3oeUWw1ZSSF8F/141moWsGxSnd5NxCbPUWGoRfYcHc865E70nN4WrZkM7RFI/s5mvQtuj8dRL67JUEwvdvEDO0EBz21FV/iOracXd2omlTUSK+wYrWGtiwQwEgr4r5bimxDKy9L8UlaJZ+ONhLTP8ecTHYkaU1C75sLX9ZYd5YtqjiNGsNF+wdW6WrXrQiWeyrGK7ZwbA7lagSxIa7yeqnKDjdkcJvQXCYGLM9AMBKWeJaOpwqZ+dOunMDLd5VZrDCU2lpCSJ1M=" + # use the following passwordless demonstration key for testing or + # replace with your own key pair + # + # -----BEGIN OPENSSH PRIVATE KEY----- + # b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn + # NhAAAAAwEAAQAAAYEA0QiQkNVA/ULJVg0sOT8LL22tFrH9aTuIaMOQbTWmZ9MS2aU6tp6h + # RCbIVJHf8wlhew1soZjaYUPHPlPsHJnTVXINqSNZD8atFWcwX2e3A8IY4Hi7CL0171Ph1U + # bbF4eHORZVF6UY3/8fmt76hUbzbEXdQxPuWakB2zlW57ErZNz2aaWgcjIPgGWTMeejlJNq + # WQoL6QsI+iyIsasLsTSj8ZiX+OUcjrD1F8AsJKvVA+JnuY5LEzz5Ld6HlFsNWUkhfBf9eN + # ZqFrBsUp3eTcQmz1FhqEX2HB3POuRO9JzeFq2ZDO0RSP7OZr0Lbo/HUS+uyVBML3bxAztB + # Ac9tRVf4jq2nF3dqJpU1EivsGK1hrYsEMBIK+K+W4psQysvS/FJWiWfjjYS0z/HnEx2JGl + # NQu+bC1/WWHeWLao4jRrDRfsHVulq160Ilnsqxiu2cGwO5WoEsSGu8nqpyg43ZHCb0FwmB + # izPQDASlniWjqcKmfnTrpzAy3eVWawwlNpaQkidTAAAFgGKSj8diko/HAAAAB3NzaC1yc2 + # EAAAGBANEIkJDVQP1CyVYNLDk/Cy9trRax/Wk7iGjDkG01pmfTEtmlOraeoUQmyFSR3/MJ + # YXsNbKGY2mFDxz5T7ByZ01VyDakjWQ/GrRVnMF9ntwPCGOB4uwi9Ne9T4dVG2xeHhzkWVR + # elGN//H5re+oVG82xF3UMT7lmpAds5VuexK2Tc9mmloHIyD4BlkzHno5STalkKC+kLCPos + # iLGrC7E0o/GYl/jlHI6w9RfALCSr1QPiZ7mOSxM8+S3eh5RbDVlJIXwX/XjWahawbFKd3k + # 3EJs9RYahF9hwdzzrkTvSc3hatmQztEUj+zma9C26Px1EvrslQTC928QM7QQHPbUVX+I6t + # pxd3aiaVNRIr7BitYa2LBDASCvivluKbEMrL0vxSVoln442EtM/x5xMdiRpTULvmwtf1lh + # 3li2qOI0aw0X7B1bpatetCJZ7KsYrtnBsDuVqBLEhrvJ6qcoON2Rwm9BcJgYsz0AwEpZ4l + # o6nCpn5066cwMt3lVmsMJTaWkJInUwAAAAMBAAEAAAGAEuz77Hu9EEZyujLOdTnAW9afRv + # XDOZA6pS7yWEufjw5CSlMLwisR83yww09t1QWyvhRqEyYmvOBecsXgaSUtnYfftWz44apy + # /gQYvMVELGKaJAC/q7vjMpGyrxUPkyLMhckALU2KYgV+/rj/j6pBMeVlchmk3pikYrffUX + # JDY990WVO194Dm0buLRzJvfMKYF2BcfF4TvarjOXWAxSuR8www050oJ8HdKahW7Cm5S0po + # FRnNXFGMnLA62vN00vJW8V7j7vui9ukBbhjRWaJuY5rdG/UYmzAe4wvdIEnpk9xIn6JGCp + # FRYTRn7lTh5+/QlQ6FXRP8Ir1vXZFnhKzl0K8Vqh2sf4M79MsIUGAqGxg9xdhjIa5dmgp8 + # N18IEDoNEVKUbKuKe/Z5yf8Z9tmexfH1YttjmXMOojBvUHIjRS5hdI9NxnPGRLY2kjAzcm + # gV9Rv3vtdF/+zalk3fAVLeK8hXK+di/7XTvYpfJ2EZBWiNrTeagfNNGiYydsQy3zjZAAAA + # wBNRak7UrqnIHMZn7pkCTgceb1MfByaFtlNzd+Obah54HYIQj5WdZTBAITReMZNt9S5NAR + # M8sQB8UoZPaVSC3ppILIOfLhs6KYj6RrGdiYwyIhMPJ5kRWF8xGCLUX5CjwH2EOq7XhIWt + # MwEFtd/gF2Du7HUNFPsZGnzJ3e7pDKDnE7w2khZ8CIpTFgD769uBYGAtk45QYTDo5JroVM + # ZPDq08Gb/RhIgJLmIpMwyreVpLLLe8SwoMJJ+rihmnJZxO8gAAAMEA0lhiKezeTshht4xu + # rWc0NxxD84a29gSGfTphDPOrlKSEYbkSXhjqCsAZHd8S8kMr3iF6poOk3IWSvFJ6mbd3ie + # qdRTgXH9Thwk4KgpjUhNsQuYRHBbI59Mo+BxSI1B1qzmJSGdmCBL54wwzZmFKDQPQKPxiL + # n0Mlc7GooiDMjT1tbuW/O1EL5EqTRqwgWPTKhBA6r4PnGF150hZRIMooZkD2zX6b1sGojk + # QpvKkEykTwnKCzF5TXO8+wJ3qbcEo9AAAAwQD+Z0r68c2YMNpsmyj3ZKtZNPSvJNcLmyD/ + # lWoNJq3djJN4s2JbK8l5ARUdW3xSFEDI9yx/wpfsXoaqWnygP3PoFw2CM4i0EiJiyvrLFU + # r3JLfDUFRy3EJ24RsqbigmEsgQOzTl3xfzeFPfxFoOhokSvTG88PQji1AYHz5kA7p6Zfaz + # Ok11rJYIe7+e9B0lhku0AFwGyqlWQmS/MhIpnjHIk5tP4heHGSmzKQWJDbTskNWd6aq1G7 + # 6HWfDpX4HgoM8AAAALaG9sbWFuYkBhcmM= + # -----END OPENSSH PRIVATE KEY----- + diff --git a/doc/rtd/reference/yaml_examples/apk_repo.rst b/doc/rtd/reference/yaml_examples/apk_repo.rst new file mode 100644 index 00000000000..91531cefe18 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/apk_repo.rst @@ -0,0 +1,37 @@ +.. _cce-apk-repo: + +Configure APK repositories +************************** + +These examples show how to configure the ``/etc/apk/repositories`` file. For a +full list of keys, refer to the +:ref:`APK configure module ` schema. + +Keep the existing ``/etc/apk/repositories`` file unaltered. + +.. literalinclude:: ../../../module-docs/cc_apk_configure/example1.yaml + :language: yaml + :linenos: + +Alpine v3.12 +============ + +Create the repositories file for Alpine v3.12 main and community, using the +default mirror site. + +.. literalinclude:: ../../../module-docs/cc_apk_configure/example2.yaml + :language: yaml + :linenos: + +Alpine Edge +=========== + +Create the repositories file for Alpine Edge main, community, and testing, +using a specified mirror site and a local repo. + +.. literalinclude:: ../../../module-docs/cc_apk_configure/example3.yaml + :language: yaml + :linenos: + +.. LINKS +.. _APK configure module: https://cloudinit.readthedocs.io/en/latest/reference/modules.html#apk-configure diff --git a/doc/rtd/reference/yaml_examples/apt.rst b/doc/rtd/reference/yaml_examples/apt.rst new file mode 100644 index 00000000000..6369b7505a4 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/apt.rst @@ -0,0 +1,369 @@ +.. _cce-apt: + +Additional APT config and repos +******************************* + +For a full list of keys, refer to the +:ref:`APT configure module ` schema. + +Example 1 +========= + +Cloud-init version 23.4 will generate a ``deb822``-formatted ``sources`` file +at ``/etc/apt/sources.list.d/.sources`` instead of +``/etc/apt/sources.list`` when ``sources_list`` content is in ``deb822`` +format. + +.. literalinclude:: ../../../module-docs/cc_apt_configure/example2.yaml + :language: yaml + :linenos: + +Example 2 +========= + +.. literalinclude:: ../../../module-docs/cc_apt_configure/example1.yaml + :language: yaml + :linenos: + +Explanation of APT config +========================= + +The APT config consists of two major "areas": + +* Global configuration for the APT feature +* The source dictionary, which defines various entries to be considered by APT + +Global APT configuration +======================== + +``preserve_sources_list`` +------------------------- + +Preserves the existing ``/etc/apt/sources.list``. + +Default: ``false`` - do overwrite ``sources_list``. If set to ``true`` then +any "mirrors" configuration will have no effect. + +Set to ``true`` to avoid affecting ``sources.list``. In that case only "extra" +source specifications will be written into ``/etc/apt/sources.list.d/*`` + +``disable_suites`` +------------------ + +This is an empty list by default, so nothing is disabled. + +If given, those suites are removed from ``sources.list`` after all other +modifications have been made. + +Suites are even disabled if no other modification was made, but not if +``preserve_sources_list`` is active. + +There is a special alias ``$RELEASE`` as in the sources that will be replaced +by the matching release. + +To ease configuration and improve readability the following common Ubuntu +suites will be automatically mapped to their full definition: + +- ``updates`` => ``$RELEASE-updates`` +- ``backports`` => ``$RELEASE-backports`` +- ``security`` => ``$RELEASE-security`` +- ``proposed`` => ``$RELEASE-proposed`` +- ``release`` => ``$RELEASE`` + +There is no harm in specifying a suite to be disabled that is not found in the +``sources.list`` file (just a no-op then). + +.. note:: + Lines don't get deleted, but rather disabled by being converted to a + comment. The example below disables all the usual defaults except + ``$RELEASE-security``. It also disables a custom suite called "mysuite". + +``primary``/``security`` archives +--------------------------------- + +Default: none - instead it is auto select based on cloud metadata so if +none of ``uri``, ``search``, or ``search_dns`` are set (the default) then use +the mirror provided by the DataSource found. In EC2, that means using +``.ec2.archive.ubuntu.com``. + +``security`` is optional, if not defined it is set to the same value as +primary. + +Define a custom (e.g. localized) mirror that will be used in ``sources.list`` +and any custom sources entries for ``deb`` / ``deb-src`` lines. + +One can set primary and security mirror to different URIs. The child +elements to the keys primary and secondary are equivalent. + +* ``arches`` is list of architectures the config applies to. The special + keyword "default" applies to any architecture not explicitly listed. In the + example below, ``arches`` is set twice, which allows one to have separate + configs for different per-arch mirrors + +* ``uri`` is just defining the target as-is +* ``search`` via search one can define lists that are tried one by one. The + first with a working DNS resolution (or if it is an IP) will be picked. + That way one can keep one configuration for multiple sub-environments that + select the working one. +* ``search_dns`` If no mirror is provided by URI or search but 'search_dns' + is true, then search for DNS names ``'-mirror'`` in each of: + + - FQDN of this host per cloud metadata + - ``localdomain`` + - no domain (which would search domains listed in ``/etc/resolv.conf``) + +If there is a DNS entry for ``-mirror``, then it is assumed that +there is a distro mirror at ``http://-mirror./``. +That gives the cloud provider the opportunity to set mirrors of a distro up +and expose them only by creating DNS entries. + +If none of that is found, then the default distro mirror is used. + +If multiple of a category are given: + +1. ``uri`` +2. ``search`` +3. ``search_dns`` + +The first defining a valid mirror wins (in the order as defined here, not +the order as listed in the config). + +Additionally, if the repository requires a custom signing key, it can be +specified via the same fields as for custom sources: + +* ``keyid``: providing a key to import via shortid or fingerprint +* ``key``: providing a raw PGP key +* ``keyserver``: specify an alternate keyserver to pull keys from that were + specified by keyid + +If ``search_dns`` is set for security the searched pattern is: +``-security-mirror``. + +If no mirrors are specified at all (or all lookups fail), it will try to get +them from the cloud datasource. If neither of those provide one, it will fall +back to: + +- ``primary: http://archive.ubuntu.com/ubuntu`` +- ``security: http://security.ubuntu.com/ubuntu`` + +``sources_list`` +---------------- + +Provides a custom template for rendering ``sources.list``. Without one +provided, cloud-init uses built-in templates for Ubuntu and Debian. + +Within these ``sources.list`` templates you can use the following replacement +variables (all have sensible Ubuntu defaults, but mirrors can be overwritten +as needed (see above)): + +- ``$RELEASE`` +- ``$MIRROR`` +- ``$PRIMARY`` +- ``$SECURITY`` + +``conf`` +-------- + +Specifies any APT config string that will be made available to APT. Seee the +``APT.CONF(5)`` manpage for details of what can be specified. + +``(http_|ftp_|https_)proxy`` +---------------------------- + +Proxies are the most common ``apt.conf`` option, so for simplified use +there is a shortcut for those. They get automatically translated into the +correct ``Acquire::*::Proxy`` statements. + +.. note:: + ``proxy`` is a short synonym to ``http_proxy``. + +Source list dictionary +====================== + +This is a dictionary (unlike most block/net which are lists). + +The key of each source entry is the filename, which is prepended by +``/etc/apt/sources.list.d/`` if it doesn't start with a ``'/'``. + +If it doesn't end with ``.list`` it will be appended so that APT picks up its +configuration. + +Whenever there is no content to be written into such a file, the key is +not used as filename -- yet it can still be used as index for merging +configuration. + +The values inside the entries consist of the following optional entries: + +- ``source``: A ``sources.list`` entry (some variable replacements apply) +- ``keyid``: Providing a key to import via short ID or fingerprint +- ``key``: Providing a raw PGP key +- ``keyserver``: Specify an alternate keyserver to pull the keys from that + were specified by ``keyid`` + +This allows merging between multiple input files given a list like: + +.. code-block:: yaml + + cloud-config1 + sources: + s1: {'key': 'key1', 'source': 'source1'} + cloud-config2 + sources: + s2: {'key': 'key2'} + s1: {'keyserver': 'foo'} + +This would be merged to: + +.. code-block:: yaml + + sources: + s1: + keyserver: foo + key: key1 + source: source1 + s2: + key: key2 + +Sources example +--------------- + +.. code-block:: yaml + + #cloud-config + apt_pipelining: False + packages: ['pastebinit'] + apt: + preserve_sources_list: true + disable_suites: [$RELEASE-updates, backports, $RELEASE, mysuite] + primary: + - arches: [amd64, i386, default] + uri: http://us.archive.ubuntu.com/ubuntu + search: + - http://cool.but-sometimes-unreachable.com/ubuntu + - http://us.archive.ubuntu.com/ubuntu + search_dns: true + - arches: [s390x, arm64] + security: + - uri: http://security.ubuntu.com/ubuntu + arches: [default] + sources_list: | # written by cloud-init custom template + deb $MIRROR $RELEASE main restricted + deb-src $MIRROR $RELEASE main restricted + deb $PRIMARY $RELEASE universe restricted + deb $SECURITY $RELEASE-security multiverse + conf: | # APT config + APT { + Get { + Assume-Yes "true"; + Fix-Broken "true"; + }; + }; + + proxy: http://[[user][:pass]@]host[:port]/ + http_proxy: http://[[user][:pass]@]host[:port]/ + ftp_proxy: ftp://[[user][:pass]@]host[:port]/ + https_proxy: https://[[user][:pass]@]host[:port]/ + add_apt_repo_match: '^[\w-]+:\w' + sources: + curtin-dev-ppa.list: + source: "deb http://ppa.launchpad.net/curtin-dev/test-archive/ubuntu bionic main" + keyid: F430BBA5 # GPG key ID published on a key server + ignored1: + source: "ppa:curtin-dev/test-archive" # Quote the string + my-repo2.list: + source: deb [signed-by=$KEY_FILE] $MIRROR $RELEASE multiverse + keyid: F430BBA5 + my-repo3.list: + source: "deb http://ppa.launchpad.net/curtin-dev/test-archive/ubuntu bionic main" + keyid: F430BBA5 # GPG key ID published on the key server + filename: curtin-dev-ppa.list + ignored2: + keyid: F430BBA5 # GPG key ID published on a key server + ignored3: + keyid: B59D 5F15 97A5 04B7 E230 6DCA 0620 BBCF 0368 3F77 + ignored4: + keyid: B59D 5F15 97A5 04B7 E230 6DCA 0620 BBCF 0368 3F77 + keyserver: pgp.mit.edu + ignored5: + source: deb [signed-by=$KEY_FILE] $MIRROR $RELEASE multiverse + keyid: B59D 5F15 97A5 04B7 E230 6DCA 0620 BBCF 0368 3F77 + my-repo4.list: + key: | + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: SKS 1.0.10 + mI0ESpA3UQEEALdZKVIMq0j6qWAXAyxSlF63SvPVIgxHPb9Nk0DZUixn+akqytxG4zKCONz6 + qLjoBBfHnynyVLfT4ihg9an1PqxRnTO+JKQxl8NgKGz6Pon569GtAOdWNKw15XKinJTDLjnj + 9y96ljJqRcpV9t/WsIcdJPcKFR5voHTEoABE2aEXABEBAAG0GUxhdW5jaHBhZCBQUEEgZm9y + IEFsZXN0aWOItgQTAQIAIAUCSpA3UQIbAwYLCQgHAwIEFQIIAwQWAgMBAh4BAheAAAoJEA7H + 5Qi+CcVxWZ8D/1MyYvfj3FJPZUm2Yo1zZsQ657vHI9+pPouqflWOayRR9jbiyUFIn0VdQBrP + t0FwvnOFArUovUWoKAEdqR8hPy3M3APUZjl5K4cMZR/xaMQeQRZ5CHpS4DBKURKAHC0ltS5o + uBJKQOZm5iltJp15cgyIkBkGe8Mx18VFyVglAZey + =Y2oI + -----END PGP PUBLIC KEY BLOCK----- + +Breakdown of the entries in the ``sources:`` list: + +* ``curtin-dev-ppa.list:`` + + - ``source:`` Creates a file in ``/etc/apt/sources.list.d/`` for the sources + list entry based on the key: + ``/etc/apt/sources.list.d/curtin-dev-ppa.list`` + + - ``keyid:`` Imports a GPG key for a given ``keyid``. Used keyserver defaults + to ``keyserver.ubuntu.com``. + +* ``ignored1:`` + + - ``source:`` Creates a PPA shortcut, setting up the correct APT + ``sources.list`` line and auto-imports the signing key from Launchpad. + + See ``https://help.launchpad.net/Packaging/PPA`` for more information. + This requires ``'add-apt-repository'``, and will create a file in + ``/etc/apt/sources.list.d`` automatically, therefore the key here is + ignored as filename in those cases. + +* ``my-repo2.list:`` + + - ``source:`` Uses replacement variables. Sources can use ``$MIRROR``, + ``$PRIMARY``, ``$SECURITY``, ``$RELEASE`` and ``$KEY_FILE`` replacement + variables. They will be replaced with the default or specified mirrors and + the running release. The entry in this example may be turned into e.g.: + ``source: deb http://archive.ubuntu.com/ubuntu bionic multiverse`` + +* ``my-repo3.list:`` + + - This would have the same end effect as ``'ppa:curtin-dev/test-archive'``. + +* ``ignored2:`` + + - Specifying only the key would result in only importing the key without + adding a PPA or other source spec. Since this doesn't generate a + ``source.list`` file the filename key is ignored. + +* ``ignored3:`` + + - Alternative ``keyid`` can also be specified via their long fingerprints. + +* ``ignored4:`` + + - Alternative keyservers can also be specified to fetch keys from. + +* ``ignored5:`` + + - One can specify ``[signed-by=$KEY_FILE]`` in the source definition, which + will install the key in the directory ``/etc/cloud-init.gpg.d/`` and the + ``$KEY_FILE`` replacement variable will be replaced with the path to the + specified key. If ``$KEY_FILE`` is used, but no key is specified, + APT update will (rightfully) fail due to an invalid value. + +* ``my-repo4.list:`` + + - The APT signing key can also be specified by providing a PGP public key + block. Providing the PGP key this way is the most robust method for + specifying a key, as it removes dependency on a remote key server. + + As with ``keyid``, this can be specified with or without some actual source + content. + +.. LINKS +.. _APT configure module: https://cloudinit.readthedocs.io/en/latest/reference/modules.html#apt-configure diff --git a/doc/rtd/reference/yaml_examples/apt_pipeline.rst b/doc/rtd/reference/yaml_examples/apt_pipeline.rst new file mode 100644 index 00000000000..9cc468fb27b --- /dev/null +++ b/doc/rtd/reference/yaml_examples/apt_pipeline.rst @@ -0,0 +1,35 @@ +.. _cce-apt-pipeline: + +APT pipelining +************** + +For a full list of keys, refer to the +:ref:`APT pipelining module ` schema. + +Example 1 +========= + +This example disables pipelining. + +.. literalinclude:: ../../../module-docs/cc_apt_pipelining/example1.yaml + :language: yaml + :linenos: + +Example 2 +========= + +This setting is the default -- uses the default for the distribution. + +.. literalinclude:: ../../../module-docs/cc_apt_pipelining/example2.yaml + :language: yaml + :linenos: + +Example 3 +========= + +Manually specify a pipeline depth of three. This method is not recommended. + +.. literalinclude:: ../../../module-docs/cc_apt_pipelining/example3.yaml + :language: yaml + :linenos: + diff --git a/doc/rtd/reference/yaml_examples/apt_repos.rst b/doc/rtd/reference/yaml_examples/apt_repos.rst new file mode 100644 index 00000000000..edc424e5d3b --- /dev/null +++ b/doc/rtd/reference/yaml_examples/apt_repos.rst @@ -0,0 +1,78 @@ +.. _cce-add-apt-repos: + +Add primary APT repositories +**************************** + +This example adds ``apt`` repository configuration to the system. + +* For a full list of accepted keys, refer to the `apt configure module docs`_ + +.. note:: + To add 3rd party repositories, see ``cloud-config-apt.txt`` or the + :ref:`additional apt configuration and repositories ` section. + +Specify mirrors +=============== + +* Default: auto select based on cloud metadata in EC2, the default is + ``.archive.ubuntu.com``. + +One can either specify a URI to use as a mirror with the ``uri`` key, or a list +of URLs using the ``search`` key, which will have cloud-init search the list +for the first mirror available. This option is limited in that it only verifies +that the mirror is DNS-resolvable (or an IP address). + +If neither mirror is set (the default), then use the mirror provided by the +DataSource. In EC2, that means using ``.ec2.archive.ubuntu.com``. + +If no mirror is provided by the DataSource, but ``search_dns`` is true, then +search for DNS names ``-mirror`` in each of: +- FQDN of this host per cloud metadata +- localdomain +- no domain (which would search domains listed in ``/etc/resolv.conf``) + +If there is a DNS entry for ``-mirror``, then it is assumed that there +is a distro mirror at ``http://-mirror./``. That gives +the cloud provider the opportunity to set up mirrors of a distro and expose +them only by creating DNS entries. + +If none of that is found, then the default distro mirror is used. + +.. code-block:: yaml + + #cloud-config + apt: + primary: + - arches: [default] + uri: http://us.archive.ubuntu.com/ubuntu/ + # or + apt: + primary: + - arches: [default] + search: + - http://local-mirror.mydomain + - http://archive.ubuntu.com + # or + apt: + primary: + - arches: [default] + search_dns: True + +Update APT on first boot +======================== + +This example will update the ``apt`` repository on first boot; it runs the +``apt-get update`` command. + + +The default is ``false``. However, if packages are given, or if +``package_upgrade`` is set to ``true``, then the update will be done +irrespective of this setting. + +.. code-block:: yaml + + #cloud-config + package_update: true + +.. LINKS +.. _apt configure module docs: https://cloudinit.readthedocs.io/en/latest/reference/modules.html#apt-configure diff --git a/doc/rtd/reference/yaml_examples/archive.rst b/doc/rtd/reference/yaml_examples/archive.rst new file mode 100644 index 00000000000..698d8e08de7 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/archive.rst @@ -0,0 +1,20 @@ +.. _cce-archive: + +Archive +******* + +.. code-block:: yaml + + #cloud-config-archive + - type: foo/wark + filename: bar + content: | + This is my payload + hello + - this is also payload + - | + multi line payload + here + - + type: text/cloud-config + content: '#cloud-config\n\n password: gocubs' diff --git a/doc/rtd/reference/yaml_examples/archive_launch_index.rst b/doc/rtd/reference/yaml_examples/archive_launch_index.rst new file mode 100644 index 00000000000..a4a47d8bcd8 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/archive_launch_index.rst @@ -0,0 +1,33 @@ +.. _cce-archive-launch-index: + +Cloud archive launch indexes +**************************** + +This is an example of a cloud archive format which includes a set of launch +indexes that will be filtered on (thus only showing up in instances with that +launch index). This is done by adding the ``launch-index`` key which maps to +the integer ``launch-index`` that the corresponding content should be used +with. + +It is possible to leave this value out which means that the content will be +applicable for all instances. + +.. code-block:: yaml + + #cloud-config-archive + - type: foo/wark + filename: bar + content: | + This is my payload + hello + launch-index: 1 # Will only be used on launch-index 1 + - this is also payload + - | + multi line payload + here + - + type: text/upstart-job + filename: my-upstart.conf + content: | + whats this, yo?s + launch-index: 0 # Will only be used on launch-index 0 diff --git a/doc/rtd/reference/yaml_examples/boot_cmds.rst b/doc/rtd/reference/yaml_examples/boot_cmds.rst new file mode 100644 index 00000000000..ca8f00eda84 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/boot_cmds.rst @@ -0,0 +1,50 @@ +.. _cce-boot-cmds: + +Run commands during boot +************************ + +Both ``runcmd`` and ``bootcmd`` can be used to run commands during the boot +process. + +- ``bootcmd`` runs on every boot, and is typically used to run commands very + early in the boot process (just after a boothook, and often before other + cloud-init modules have run). +- ``runcmd`` only runs on first boot, **after** the instance has been started + and all other configuration has been applied. + +Run commands only on first boot +=============================== + +``runcmd`` contains either a list of lists or a list of strings. Each item is +run in order, with output printed to the console. + +The list must be written in proper YAML -- be sure to quote any characters +such as colons (``:``) that would otherwise be "eaten". + +For a full list of keys, refer to the :ref:`runcmd module ` +schema. + +.. literalinclude:: ../../../module-docs/cc_runcmd/example1.yaml + :language: yaml + :linenos: + +.. note:: + Don't write files to ``/tmp`` from cloud-init -- use ``/run/somedir`` + instead. Early boot environments can race ``systemd-tmpfiles-clean`` (LP: + #1707222). + +Run commands in early boot +========================== + +- The ``INSTANCE_ID`` variable will be set to the current instance ID by + default. +- The ``cloud-init-per`` command can be used to make ``bootcmd`` run exactly + once. + +For a full list of keys, refer to the :ref:`bootcmd module ` +schema. + +.. literalinclude:: ../../../module-docs/cc_bootcmd/example1.yaml + :language: yaml + :linenos: + diff --git a/doc/rtd/reference/yaml_examples/byobu.rst b/doc/rtd/reference/yaml_examples/byobu.rst new file mode 100644 index 00000000000..2fe51de577a --- /dev/null +++ b/doc/rtd/reference/yaml_examples/byobu.rst @@ -0,0 +1,22 @@ +.. _cce-byobu: + +Enable/disable Byobu +******************** + +For a full list of keys, refer to the :ref:`Byobu module ` +schema. + +Enable for the default user +=========================== + +.. literalinclude:: ../../../module-docs/cc_byobu/example1.yaml + :language: yaml + :linenos: + +Disable system-wide +=================== + +.. literalinclude:: ../../../module-docs/cc_byobu/example2.yaml + :language: yaml + :linenos: + diff --git a/doc/rtd/reference/yaml_examples/ca_certs.rst b/doc/rtd/reference/yaml_examples/ca_certs.rst new file mode 100644 index 00000000000..657b2c20bfe --- /dev/null +++ b/doc/rtd/reference/yaml_examples/ca_certs.rst @@ -0,0 +1,52 @@ +.. _cce-ca-certs: + +Add and configure trusted CA certificates +***************************************** + +These examples demonstrate adding CA certificates to the system's CA store, +and configuring the same. + +For a full list of keys, refer to the +:ref:`CA certificates module ` schema. + +Add a single-line certificate +============================= + +.. literalinclude:: ../../../module-docs/cc_ca_certs/example1.yaml + :language: yaml + :linenos: + +Configure multiline certificates +================================ + +This example configures CA certificates (system-wide) to establish SSL/TLS +trust when the instance boots for the first time. + +- If present and set to ``true``, the ``remove_defaults`` parameter will + disable all trusted CA certifications normally shipped with Alpine, Debian or + Ubuntu. On RedHat, this action will delete those certificates. + + This is primarily for security-sensitive use cases -- most users will not + need this functionality. + +- If present, the ``trusted`` parameter should contain a certificate (or list + of certificates) to add to the system as trusted CA certificates. + + In this example, note the YAML multiline list syntax, which configures a list + of multiline certificates. + +.. code-block:: yaml + + #cloud-config + ca_certs: + remove_defaults: true + trusted: + - | + -----BEGIN CERTIFICATE----- + YOUR-ORGS-TRUSTED-CA-CERT-HERE + -----END CERTIFICATE----- + - | + -----BEGIN CERTIFICATE----- + YOUR-ORGS-TRUSTED-CA-CERT-HERE + -----END CERTIFICATE----- + diff --git a/doc/rtd/reference/yaml_examples/chef.rst b/doc/rtd/reference/yaml_examples/chef.rst new file mode 100644 index 00000000000..6d930b7dbb4 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/chef.rst @@ -0,0 +1,179 @@ +.. _cce-chef: + +Install and run Chef recipes +**************************** + +This example file automatically installs the Chef client and runs a list of +recipes when the instance boots for the first time. It should be passed as user +data when starting the instance. + +The default is to install from packages. + +The key used in this example is from https://packages.chef.io/chef.asc. + +For a full list of accepted keys, refer to the :ref:`Chef module ` +schema. + +Example 1 +========= + +.. literalinclude:: ../../../module-docs/cc_chef/example1.yaml + :language: yaml + :linenos: + +Example 2 +========= + +.. code-block:: yaml + + #cloud-config + apt: + sources: + source1: + source: "deb http://packages.chef.io/repos/apt/stable $RELEASE main" + key: | + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (Darwin) + Comment: GPGTools - http://gpgtools.org + mQGiBEppC7QRBADfsOkZU6KZK+YmKw4wev5mjKJEkVGlus+NxW8wItX5sGa6kdUu + twAyj7Yr92rF+ICFEP3gGU6+lGo0Nve7KxkN/1W7/m3G4zuk+ccIKmjp8KS3qn99 + dxy64vcji9jIllVa+XXOGIp0G8GEaj7mbkixL/bMeGfdMlv8Gf2XPpp9vwCgn/GC + JKacfnw7MpLKUHOYSlb//JsEAJqao3ViNfav83jJKEkD8cf59Y8xKia5OpZqTK5W + ShVnNWS3U5IVQk10ZDH97Qn/YrK387H4CyhLE9mxPXs/ul18ioiaars/q2MEKU2I + XKfV21eMLO9LYd6Ny/Kqj8o5WQK2J6+NAhSwvthZcIEphcFignIuobP+B5wNFQpe + DbKfA/0WvN2OwFeWRcmmd3Hz7nHTpcnSF+4QX6yHRF/5BgxkG6IqBIACQbzPn6Hm + sMtm/SVf11izmDqSsQptCrOZILfLX/mE+YOl+CwWSHhl+YsFts1WOuh1EhQD26aO + Z84HuHV5HFRWjDLw9LriltBVQcXbpfSrRP5bdr7Wh8vhqJTPjrQnT3BzY29kZSBQ + YWNrYWdlcyA8cGFja2FnZXNAb3BzY29kZS5jb20+iGAEExECACAFAkppC7QCGwMG + CwkIBwMCBBUCCAMEFgIDAQIeAQIXgAAKCRApQKupg++Caj8sAKCOXmdG36gWji/K + +o+XtBfvdMnFYQCfTCEWxRy2BnzLoBBFCjDSK6sJqCu0IENIRUYgUGFja2FnZXMg + PHBhY2thZ2VzQGNoZWYuaW8+iGIEExECACIFAlQwYFECGwMGCwkIBwMCBhUIAgkK + CwQWAgMBAh4BAheAAAoJEClAq6mD74JqX94An26z99XOHWpLN8ahzm7cp13t4Xid + AJ9wVcgoUBzvgg91lKfv/34cmemZn7kCDQRKaQu0EAgAg7ZLCVGVTmLqBM6njZEd + Zbv+mZbvwLBSomdiqddE6u3eH0X3GuwaQfQWHUVG2yedyDMiG+EMtCdEeeRebTCz + SNXQ8Xvi22hRPoEsBSwWLZI8/XNg0n0f1+GEr+mOKO0BxDB2DG7DA0nnEISxwFkK + OFJFebR3fRsrWjj0KjDxkhse2ddU/jVz1BY7Nf8toZmwpBmdozETMOTx3LJy1HZ/ + Te9FJXJMUaB2lRyluv15MVWCKQJro4MQG/7QGcIfrIZNfAGJ32DDSjV7/YO+IpRY + IL4CUBQ65suY4gYUG4jhRH6u7H1p99sdwsg5OIpBe/v2Vbc/tbwAB+eJJAp89Zeu + twADBQf/ZcGoPhTGFuzbkcNRSIz+boaeWPoSxK2DyfScyCAuG41CY9+g0HIw9Sq8 + DuxQvJ+vrEJjNvNE3EAEdKl/zkXMZDb1EXjGwDi845TxEMhhD1dDw2qpHqnJ2mtE + WpZ7juGwA3sGhi6FapO04tIGacCfNNHmlRGipyq5ZiKIRq9mLEndlECr8cwaKgkS + 0wWu+xmMZe7N5/t/TK19HXNh4tVacv0F3fYK54GUjt2FjCQV75USnmNY4KPTYLXA + dzC364hEMlXpN21siIFgB04w+TXn5UF3B4FfAy5hevvr4DtV4MvMiGLu0oWjpaLC + MpmrR3Ny2wkmO0h+vgri9uIP06ODWIhJBBgRAgAJBQJKaQu0AhsMAAoJEClAq6mD + 74Jq4hIAoJ5KrYS8kCwj26SAGzglwggpvt3CAJ0bekyky56vNqoegB+y4PQVDv4K + zA== + =IxPr + -----END PGP PUBLIC KEY BLOCK----- + chef: + chef_license: accept + encrypted_data_bag_secret: /etc/chef/encrypted_data_bag_secret + environment: production + force_install: false + initial_attributes: + apache: + prefork: {maxclients: 100} + keepalive: false + install_type: packages + node_name: your-node-name + omnibus_url: https://www.chef.io/chef/install.sh + omnibus_version: 12.3.0 + run_list: ['recipe[apache2]', 'role[db]'] + server_url: https://chef.yourorg.com + validation_name: yourorg-validator + validation_cert: | + -----BEGIN RSA PRIVATE KEY----- + YOUR-ORGS-VALIDATION-KEY-HERE + -----END RSA PRIVATE KEY----- + +.. note:: + - ``chef_license``: Valid values are 'accept' and 'accept-no-persist'. + - ``install_type``: Valid values are 'gems', 'packages' and 'omnibus'. If + ``install_type`` is 'omnibus', pass pinned version string to the install + script via ``omnibus_version``, and change the url to download via + ``omnibus_url``. + - ``force_install``: (boolean) run ``install_type`` code even if + ``chef-client`` appears to be already installed. + - If ``validation_cert``'s value is "system" then it is expected that the + file already exists on the system. + - If encrypted data bags are used, the client needs to have a secrets file + configured to decrypt them + + +Chef oneiric +============ + +This example file, as in the example above, automatically installs the Chef +client and runs a list of recipes when the instance boots for the first time. + +However, in this case, the example uses the instance 11.10 (oneiric). The file +should be passed as user-data when starting the instance. + +The default is to install from packages. + +The key used in this example is from +http://apt.opscode.com/packages@opscode.com.gpg.key. + +.. code-block:: yaml + + #cloud-config + apt: + sources: + source1: + source: "deb http://apt.opscode.com/ $RELEASE-0.10 main" + key: | + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.9 (GNU/Linux) + mQGiBEppC7QRBADfsOkZU6KZK+YmKw4wev5mjKJEkVGlus+NxW8wItX5sGa6kdUu + twAyj7Yr92rF+ICFEP3gGU6+lGo0Nve7KxkN/1W7/m3G4zuk+ccIKmjp8KS3qn99 + dxy64vcji9jIllVa+XXOGIp0G8GEaj7mbkixL/bMeGfdMlv8Gf2XPpp9vwCgn/GC + JKacfnw7MpLKUHOYSlb//JsEAJqao3ViNfav83jJKEkD8cf59Y8xKia5OpZqTK5W + ShVnNWS3U5IVQk10ZDH97Qn/YrK387H4CyhLE9mxPXs/ul18ioiaars/q2MEKU2I + XKfV21eMLO9LYd6Ny/Kqj8o5WQK2J6+NAhSwvthZcIEphcFignIuobP+B5wNFQpe + DbKfA/0WvN2OwFeWRcmmd3Hz7nHTpcnSF+4QX6yHRF/5BgxkG6IqBIACQbzPn6Hm + sMtm/SVf11izmDqSsQptCrOZILfLX/mE+YOl+CwWSHhl+YsFts1WOuh1EhQD26aO + Z84HuHV5HFRWjDLw9LriltBVQcXbpfSrRP5bdr7Wh8vhqJTPjrQnT3BzY29kZSBQ + YWNrYWdlcyA8cGFja2FnZXNAb3BzY29kZS5jb20+iGAEExECACAFAkppC7QCGwMG + CwkIBwMCBBUCCAMEFgIDAQIeAQIXgAAKCRApQKupg++Caj8sAKCOXmdG36gWji/K + +o+XtBfvdMnFYQCfTCEWxRy2BnzLoBBFCjDSK6sJqCu5Ag0ESmkLtBAIAIO2SwlR + lU5i6gTOp42RHWW7/pmW78CwUqJnYqnXROrt3h9F9xrsGkH0Fh1FRtsnncgzIhvh + DLQnRHnkXm0ws0jV0PF74ttoUT6BLAUsFi2SPP1zYNJ9H9fhhK/pjijtAcQwdgxu + wwNJ5xCEscBZCjhSRXm0d30bK1o49Cow8ZIbHtnXVP41c9QWOzX/LaGZsKQZnaMx + EzDk8dyyctR2f03vRSVyTFGgdpUcpbr9eTFVgikCa6ODEBv+0BnCH6yGTXwBid9g + w0o1e/2DviKUWCC+AlAUOubLmOIGFBuI4UR+rux9affbHcLIOTiKQXv79lW3P7W8 + AAfniSQKfPWXrrcAAwUH/2XBqD4Uxhbs25HDUUiM/m6Gnlj6EsStg8n0nMggLhuN + QmPfoNByMPUqvA7sULyfr6xCYzbzRNxABHSpf85FzGQ29RF4xsA4vOOU8RDIYQ9X + Q8NqqR6pydprRFqWe47hsAN7BoYuhWqTtOLSBmnAnzTR5pURoqcquWYiiEavZixJ + 3ZRAq/HMGioJEtMFrvsZjGXuzef7f0ytfR1zYeLVWnL9Bd32CueBlI7dhYwkFe+V + Ep5jWOCj02C1wHcwt+uIRDJV6TdtbIiBYAdOMPk15+VBdweBXwMuYXr76+A7VeDL + zIhi7tKFo6WiwjKZq0dzctsJJjtIfr4K4vbiD9Ojg1iISQQYEQIACQUCSmkLtAIb + DAAKCRApQKupg++CauISAJ9CxYPOKhOxalBnVTLeNUkAHGg2gACeIsbobtaD4ZHG + 0GLl8EkfA8uhluM= + =zKAm + -----END PGP PUBLIC KEY BLOCK----- + chef: + environment: "production" + initial_attributes: + apache: + keepalive: false + prefork: {maxclients: 100} + install_type: packages + node_name: your-node-name + run_list: ['recipe[apache2]', 'role[db]'] + server_url: https://chef.yourorg.com:4000 + validation_cert: unused + validation_name: yourorg-validator + validation_key: | + -----BEGIN RSA PRIVATE KEY----- + YOUR-ORGS-VALIDATION-KEY-HERE + -----END RSA PRIVATE KEY----- + +.. note:: + 11.10 will fail if ``install_type`` is "gems" (LP: #960576). + + The value of ``validation_cert`` is not used if ``validation_key`` is + defined, but the variable needs to be defined (LP: #960547). + +.. LINKS +.. _chef: http://www.chef.io/chef/ + diff --git a/doc/rtd/reference/yaml_examples/datasources.rst b/doc/rtd/reference/yaml_examples/datasources.rst new file mode 100644 index 00000000000..dc3f3d1afc5 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/datasources.rst @@ -0,0 +1,95 @@ +.. _cce-datasources: + +Configure datasources +********************* + +These examples show datasource configuration options for various datasources. + +The options shown are as follows: + +* ``timeout``: The timeout value for a request at metadata service +* ``max_wait``: The length of time to wait (in seconds) before giving up on + the metadata service. The actual total wait could be up to: + ``len(resolvable_metadata_urls)*timeout`` +* ``metadata_url``: List of URLs to check for metadata services. There are no + default values for this field. + +EC2 +=== + +.. code-block:: yaml + + #cloud-config + datasource: + EC2: + timeout : 50 + max_wait : 120 + metadata_url: + - http://169.254.169.254:80 + - http://instance-data:8773 + +MAAS +==== + +.. code-block:: yaml + + #cloud-config + datasource: + MAAS: + timeout : 50 + max_wait : 120 + metadata_url: http://mass-host.localdomain/source + consumer_key: Xh234sdkljf + token_key: kjfhgb3n + token_secret: 24uysdfx1w4 + +NoCloud +======= + +.. code-block:: yaml + + #cloud-config + datasource: + NoCloud: + seedfrom: None + fs_label: cidata + user-data: | + # This is the user-data verbatim + meta-data: + instance-id: i-87018aed + local-hostname: myhost.internal + +* ``seedfrom``: The default value is None. If found, it should contain a URL + with ``/user-data`` and ``/meta-data``. For example: + ``seedfrom: http://my.example.com/i-abcde/`` +* ``fs_label``: The label on filesystems to be searched for NoCloud source +* ``user-data`` and ``meta-data`` (optional): Allows a datasource to be + provided directly. + +SmartOS +======= + +.. code-block:: yaml + + #cloud-config + datasource: + SmartOS: + # For KVM guests: + # Smart OS datasource works over a serial console interacting with + # a server on the other end. By default, the second serial console is the + # device. SmartOS also uses a serial timeout of 60 seconds. + serial_device: /dev/ttyS1 + serial_timeout: 60 + # For LX-Brand Zones guests: + # Smart OS datasource works over a socket interacting with + # the host on the other end. By default, the socket file is in + # the native .zoncontrol directory. + metadata_sockfile: /native/.zonecontrol/metadata.sock + # a list of keys that will not be base64 decoded even if base64_all + no_base64_decode: ['root_authorized_keys', 'motd_sys_info', + 'iptables_disable'] + # a plaintext, comma delimited list of keys whose values are b64 encoded + base64_keys: [] + # a boolean indicating that all keys not in 'no_base64_decode' are encoded + base64_all: False + diff --git a/doc/rtd/reference/yaml_examples/disable_ec2_metadata.rst b/doc/rtd/reference/yaml_examples/disable_ec2_metadata.rst new file mode 100644 index 00000000000..e4047c11d62 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/disable_ec2_metadata.rst @@ -0,0 +1,15 @@ +.. _cce-disable-ec2-metadata: + +Disable AWS EC2 metadata +************************ + +The default value for this module is ``false``. Setting it to ``true`` disables +the IPv4 routes to EC2 metadata. + +For more details, refer to the +:ref:`disable EC2 metadata module ` schema. + +.. literalinclude:: ../../../module-docs/cc_disable_ec2_metadata/example1.yaml + :language: yaml + :linenos: + diff --git a/doc/rtd/reference/yaml_examples/disk_setup.rst b/doc/rtd/reference/yaml_examples/disk_setup.rst new file mode 100644 index 00000000000..afc9393e8c4 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/disk_setup.rst @@ -0,0 +1,324 @@ +.. _cce-disk-setup: + +Configure partitions and filesystems +************************************ + +Cloud-init supports the creation of simple partition tables and filesystems +on devices. + +- Disk partitioning is done using the ``disk_setup`` directive. +- File system configuration is done using the ``fs_setup`` directive. + +For a full list of keys, refer to the `disk setup module`_ schema. + +General example +=============== + +.. literalinclude:: ../../../module-docs/cc_disk_setup/example1.yaml + :language: yaml + :linenos: + +Disk partitioning +================= + +The ``disk_setup`` directive instructs Cloud-init to partition a disk. The +format is: + +.. code-block:: yaml + + #cloud-config + disk_setup: + ephemeral0: + table_type: 'mbr' + layout: true + /dev/xvdh: + table_type: 'mbr' + layout: + - 33 + - [33, 82] + - 33 + overwrite: True + +The format is a list of "dicts of dicts". The first value is the name of the +device and the subsequent values define how to create and lay out the +partition. The general format is: + +.. code-block:: yaml + + disk_setup: + : + table_type: 'mbr' + layout: + overwrite: + +Where: + +- ````: + The name of the device. ``ephemeralX`` and ``swap`` are special values which + are specific to the cloud. For these devices, cloud-init will look up what + the real device is and then use it. + + For other devices, the kernel device name is used. At this time, only simple + kernel devices are supported, meaning that device mapper and other targets + may not work. + + Note: There is currently no handling or setup of device mapper targets. + +- ``table_type=``: + Currently, the following are supported: + + - ``mbr``: (default) sets up an MS-DOS partition table + - ``gpt``: sets up a GPT partition table + + Note: At this time only ``mbr`` and ``gpt`` partition tables are allowed. + We anticipate that in the future we will also have ``RAID`` to create a + ``mdadm`` RAID. + +- ``layout={...}``: + The device layout. This is a list of values, with the percentage of disk that + the partition will take. Valid options are: + + - ``[, [, `` is the **percentage** of the disk to use, while + ```` is the numerical value of the partition type. + + The following sets up two partitions, with the first partition having a swap + label, taking 1/3 of the disk space, and the remainder being used as the + second partition: :: + + /dev/xvdh': + table_type: 'mbr' + layout: + - [33,82] + - 66 + overwrite: True + + - When layout is "true", it instructs cloud-init to single-partition the + entire device. + - When layout is "false" it means "don't partition" or "ignore existing + partitioning". + + If layout is set to "true" and overwrite is set to "false", cloud-init will + skip partitioning the device without a failure. + +- ``overwrite=``: This describes whether to "ride with safetys on and + everything holstered". + + - "false" is the default, which means that: + + 1. The device will be checked for a partition table + 2. The device will be checked for a filesystem + 3. If either a partition of filesystem is found, then the operation will + be **skipped**. + + - "true" is **cowboy mode**. There are no checks and things are done blindly. + Use this option only with caution, you can do things you really, really + don't want to do. + +Set up the filesystem +===================== + +``fs_setup`` describes the how the filesystems are supposed to look. + +.. code-block:: yaml + + fs_setup: + - label: ephemeral0 + filesystem: 'ext3' + device: 'ephemeral0' + partition: 'auto' + - label: mylabl2 + filesystem: 'ext4' + device: '/dev/xvda1' + - cmd: mkfs -t %(filesystem)s -L %(label)s %(device)s + label: mylabl3 + filesystem: 'btrfs' + device: '/dev/xvdh' + +The general format is: + +.. code-block:: yaml + + fs_setup: + - label: