diff --git a/doc/module-docs/cc_users_groups/example3.yaml b/doc/module-docs/cc_users_groups/example3.yaml index ed79daa9d25..b39665b1b1a 100644 --- a/doc/module-docs/cc_users_groups/example3.yaml +++ b/doc/module-docs/cc_users_groups/example3.yaml @@ -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 diff --git a/doc/module-docs/cc_users_groups/example4.yaml b/doc/module-docs/cc_users_groups/example4.yaml index 4c764b9c6fa..cd5647f85a5 100644 --- a/doc/module-docs/cc_users_groups/example4.yaml +++ b/doc/module-docs/cc_users_groups/example4.yaml @@ -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'] + diff --git a/doc/rtd/explanation/about-cloud-config.rst b/doc/rtd/explanation/about-cloud-config.rst new file mode 100644 index 00000000000..dae73a65dfc --- /dev/null +++ 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 ` 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 ` +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 `. 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 `. 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 ` 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 "

Welcome to the party, pal!

" > /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 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..c88eed3cb88 100644 --- a/doc/rtd/reference/examples.rst +++ b/doc/rtd/reference/examples.rst @@ -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 `. Including users and groups ========================== @@ -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/ + diff --git a/doc/rtd/reference/examples_library.rst b/doc/rtd/reference/examples_library.rst new file mode 100644 index 00000000000..43a34766b0b --- /dev/null +++ b/doc/rtd/reference/examples_library.rst @@ -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 `. + +.. 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 diff --git a/doc/rtd/reference/index.rst b/doc/rtd/reference/index.rst index d1791fa9631..cb6fa1736ff 100644 --- a/doc/rtd/reference/index.rst +++ b/doc/rtd/reference/index.rst @@ -12,6 +12,7 @@ matrices and so on. modules.rst examples.rst + examples_library.rst cli.rst availability.rst faq.rst 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..b7da819f310 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/ansible_controller.rst @@ -0,0 +1,146 @@ +.. _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. 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. + +.. code-block:: yaml + + #cloud-config + + # Update, upgrade and install packages + # ------------------------------------ + 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. + users: + - name: ansible + gecos: Ansible User + shell: /bin/bash + groups: users,admin,wheel,lxd + sudo: ALL=(ALL) NOPASSWD:ALL + + # Initialize LXD using cloud-init + # ------------------------------- + # A LXD container is started (using Ansible) on boot, so we must + # initialize LXD. + 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 starts a LXD container and creates a new inventory file + # * The second 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`` + 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`_. + 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..106a734ccc3 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/apt.rst @@ -0,0 +1,93 @@ +.. _cce-apt: + +Configure APT +************* + +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: + +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 + +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 + + +.. 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/boot_cmds.rst b/doc/rtd/reference/yaml_examples/boot_cmds.rst new file mode 100644 index 00000000000..d9957ffd793 --- /dev/null +++ b/doc/rtd/reference/yaml_examples/boot_cmds.rst @@ -0,0 +1,45 @@ +.. _cce-boot-cmds: + +Run commands during boot +************************ + +Both ``runcmd`` and ``bootcmd`` can be used to run commands during the boot +process. They contain 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". + +- ``runcmd`` only runs on first boot, **after** the instance has been started + and all other configuration has been applied. In general, you should use + ``runcmd`` unless you need to run something earlier in boot. +- ``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). + +For a full list of keys for these two modules, refer to the +:ref:`runcmd module ` and :ref:`bootcmd module ` +schema. + +Run commands on instance initialization +======================================= + +.. 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 ``cloud-init-per`` command can be used to make ``bootcmd`` run exactly +once. + +.. 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..1827fdf343b --- /dev/null +++ b/doc/rtd/reference/yaml_examples/disk_setup.rst @@ -0,0 +1,374 @@ +.. _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: + +Partition a disk +================ + +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: