diff options
Diffstat (limited to 'doc/rtd/topics')
| -rw-r--r-- | doc/rtd/topics/capabilities.rst | 50 | ||||
| -rw-r--r-- | doc/rtd/topics/datasources.rst | 1 | ||||
| -rw-r--r-- | doc/rtd/topics/datasources/gce.rst | 20 | ||||
| -rw-r--r-- | doc/rtd/topics/debugging.rst | 146 | ||||
| -rw-r--r-- | doc/rtd/topics/format.rst | 1 | ||||
| -rw-r--r-- | doc/rtd/topics/modules.rst | 1 |
6 files changed, 208 insertions, 11 deletions
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst index 2c8770bd..31eaba53 100644 --- a/doc/rtd/topics/capabilities.rst +++ b/doc/rtd/topics/capabilities.rst @@ -31,19 +31,49 @@ support. This allows other applications to detect what features the installed cloud-init supports without having to parse its version number. If present, this list of features will be located at ``cloudinit.version.FEATURES``. -When checking if cloud-init supports a feature, in order to not break the -detection script on older versions of cloud-init without the features list, a -script similar to the following should be used. Note that this will exit 0 if -the feature is supported and 1 otherwise:: +Currently defined feature names include: - import sys - from cloudinit import version - sys.exit('<FEATURE_NAME>' not in getattr(version, 'FEATURES', [])) + - ``NETWORK_CONFIG_V1`` support for v1 networking configuration, + see :ref:`network_config_v1` documentation for examples. + - ``NETWORK_CONFIG_V2`` support for v2 networking configuration, + see :ref:`network_config_v2` documentation for examples. -Currently defined feature names include: - - ``NETWORK_CONFIG_V1`` support for v1 networking configuration, see curtin - documentation for examples. +CLI Interface : + +``cloud-init features`` will print out each feature supported. If cloud-init +does not have the features subcommand, it also does not support any features +described in this document. + +.. code-block:: bash + + % cloud-init --help + usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force] + {init,modules,query,single,dhclient-hook,features} ... + + optional arguments: + -h, --help show this help message and exit + --version, -v show program's version number and exit + --file FILES, -f FILES + additional yaml configuration files to use + --debug, -d show additional pre-action logging (default: False) + --force force running even if no datasource is found (use at + your own risk) + + Subcommands: + {init,modules,single,dhclient-hook,features,analyze,devel} + init initializes cloud-init and performs initial modules + modules activates modules using a given configuration key + single run a single module + dhclient-hook run the dhclient hookto record network info + features list defined features + analyze Devel tool: Analyze cloud-init logs and data + devel Run development tools + + % cloud-init features + NETWORK_CONFIG_V1 + NETWORK_CONFIG_V2 + .. _Cloud-init: https://launchpad.net/cloud-init .. vi: textwidth=78 diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst index a60f5eb7..7e2854de 100644 --- a/doc/rtd/topics/datasources.rst +++ b/doc/rtd/topics/datasources.rst @@ -94,5 +94,6 @@ Follow for more information. datasources/ovf.rst datasources/smartos.rst datasources/fallback.rst + datasources/gce.rst .. vi: textwidth=78 diff --git a/doc/rtd/topics/datasources/gce.rst b/doc/rtd/topics/datasources/gce.rst new file mode 100644 index 00000000..8406695c --- /dev/null +++ b/doc/rtd/topics/datasources/gce.rst @@ -0,0 +1,20 @@ +.. _datasource_gce: + +Google Compute Engine +===================== + +The GCE datasource gets its data from the internal compute metadata server. +Metadata can be queried at the URL +'``http://metadata.google.internal/computeMetadata/v1/``' +from within an instance. For more information see the `GCE metadata docs`_. + +Currently the default project and instance level metadatakeys keys +``project/attributes/sshKeys`` and ``instance/attributes/ssh-keys`` are merged +to provide ``public-keys``. + +``user-data`` and ``user-data-encoding`` can be provided to cloud-init by +setting those custom metadata keys for an *instance*. + +.. _GCE metadata docs: https://cloud.google.com/compute/docs/storing-retrieving-metadata#querying + +.. vi: textwidth=78 diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst new file mode 100644 index 00000000..4e43dd57 --- /dev/null +++ b/doc/rtd/topics/debugging.rst @@ -0,0 +1,146 @@ +********************** +Testing and debugging cloud-init +********************** + +Overview +======== +This topic will discuss general approaches for test and debug of cloud-init on +deployed instances. + + +Boot Time Analysis - cloud-init analyze +====================================== +Occasionally instances don't appear as performant as we would like and +cloud-init packages a simple facility to inspect what operations took +cloud-init the longest during boot and setup. + +The script **/usr/bin/cloud-init** has an analyze sub-command **analyze** +which parses any cloud-init.log file into formatted and sorted events. It +allows for detailed analysis of the most costly cloud-init operations are to +determine the long-pole in cloud-init configuration and setup. These +subcommands default to reading /var/log/cloud-init.log. + +* ``analyze show`` Parse and organize cloud-init.log events by stage and +include each sub-stage granularity with time delta reports. + +.. code-block:: bash + + $ cloud-init analyze show -i my-cloud-init.log + -- Boot Record 01 -- + The total time elapsed since completing an event is printed after the "@" + character. + The time the event takes is printed after the "+" character. + + Starting stage: modules-config + |`->config-emit_upstart ran successfully @05.47600s +00.00100s + |`->config-snap_config ran successfully @05.47700s +00.00100s + |`->config-ssh-import-id ran successfully @05.47800s +00.00200s + |`->config-locale ran successfully @05.48000s +00.00100s + ... + + +* ``analyze dump`` Parse cloud-init.log into event records and return a list of +dictionaries that can be consumed for other reporting needs. + +.. code-block:: bash + + $ cloud-init analyze blame -i my-cloud-init.log + [ + { + "description": "running config modules", + "event_type": "start", + "name": "modules-config", + "origin": "cloudinit", + "timestamp": 1510807493.0 + },... + +* ``analyze blame`` Parse cloud-init.log into event records and sort them based +on highest time cost for quick assessment of areas of cloud-init that may need +improvement. + +.. code-block:: bash + + $ cloud-init analyze blame -i my-cloud-init.log + -- Boot Record 11 -- + 00.01300s (modules-final/config-scripts-per-boot) + 00.00400s (modules-final/config-final-message) + 00.00100s (modules-final/config-rightscale_userdata) + ... + + +Analyze quickstart - LXC +--------------------------- +To quickly obtain a cloud-init log try using lxc on any ubuntu system: + +.. code-block:: bash + + $ lxc init ubuntu-daily:xenial x1 + $ lxc start x1 + # Take lxc's cloud-init.log and pipe it to the analyzer + $ lxc file pull x1/var/log/cloud-init.log - | cloud-init analyze dump -i - + $ lxc file pull x1/var/log/cloud-init.log - | \ + python3 -m cloudinit.analyze dump -i - + +Analyze quickstart - KVM +--------------------------- +To quickly analyze a KVM a cloud-init log: + +1. Download the current cloud image + wget https://cloud-images.ubuntu.com/daily/server/xenial/current/xenial-server-cloudimg-amd64.img +2. Create a snapshot image to preserve the original cloud-image + +.. code-block:: bash + + $ qemu-img create -b xenial-server-cloudimg-amd64.img -f qcow2 \ + test-cloudinit.qcow2 + +3. Create a seed image with metadata using `cloud-localds` + +.. code-block:: bash + + $ cat > user-data <<EOF + #cloud-config + password: passw0rd + chpasswd: { expire: False } + EOF + $ cloud-localds my-seed.img user-data + +4. Launch your modified VM + +.. code-block:: bash + + $ kvm -m 512 -net nic -net user -redir tcp:2222::22 \ + -drive file=test-cloudinit.qcow2,if=virtio,format=qcow2 \ + -drive file=my-seed.img,if=virtio,format=raw + +5. Analyze the boot (blame, dump, show) + +.. code-block:: bash + + $ ssh -p 2222 ubuntu@localhost 'cat /var/log/cloud-init.log' | \ + cloud-init analyze blame -i - + + +Running single cloud config modules +=================================== +This subcommand is not called by the init system. It can be called manually to +load the configured datasource and run a single cloud-config module once using +the cached userdata and metadata after the instance has booted. Each +cloud-config module has a module FREQUENCY configured: PER_INSTANCE, PER_BOOT, +PER_ONCE or PER_ALWAYS. When a module is run by cloud-init, it stores a +semaphore file in +``/var/lib/cloud/instance/sem/config_<module_name>.<frequency>`` which marks +when the module last successfully ran. Presence of this semaphore file +prevents a module from running again if it has already been run. To ensure that +a module is run again, the desired frequency can be overridden on the +commandline: + +.. code-block:: bash + + $ sudo cloud-init single --name cc_ssh --frequency always + ... + Generating public/private ed25519 key pair + ... + +Inspect cloud-init.log for output of what operations were performed as a +result. diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst index 436eb00f..e25289ad 100644 --- a/doc/rtd/topics/format.rst +++ b/doc/rtd/topics/format.rst @@ -85,6 +85,7 @@ This content is a ``include`` file. The file contains a list of urls, one per line. Each of the URLs will be read, and their content will be passed through this same set of rules. Ie, the content read from the URL can be gzipped, mime-multi-part, or plain text. +If an error occurs reading a file the remaining files will not be read. Begins with: ``#include`` or ``Content-Type: text/x-include-url`` when using a MIME archive. diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst index c963c09a..cdb0f419 100644 --- a/doc/rtd/topics/modules.rst +++ b/doc/rtd/topics/modules.rst @@ -50,7 +50,6 @@ Modules .. automodule:: cloudinit.config.cc_ssh_authkey_fingerprints .. automodule:: cloudinit.config.cc_ssh_import_id .. automodule:: cloudinit.config.cc_timezone -.. automodule:: cloudinit.config.cc_ubuntu_init_switch .. automodule:: cloudinit.config.cc_update_etc_hosts .. automodule:: cloudinit.config.cc_update_hostname .. automodule:: cloudinit.config.cc_users_groups |