diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/rtd/topics/capabilities.rst | 14 | ||||
| -rw-r--r-- | doc/rtd/topics/debugging.rst | 57 | ||||
| -rw-r--r-- | doc/rtd/topics/network-config.rst | 4 | ||||
| -rw-r--r-- | doc/rtd/topics/tests.rst | 20 |
4 files changed, 51 insertions, 44 deletions
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst index ae3a0c74..3e2c9e31 100644 --- a/doc/rtd/topics/capabilities.rst +++ b/doc/rtd/topics/capabilities.rst @@ -44,13 +44,14 @@ Currently defined feature names include: CLI Interface ============= - The command line documentation is accessible on any cloud-init -installed system: +The command line documentation is accessible on any cloud-init installed +system: -.. code-block:: bash +.. code-block:: shell-session % cloud-init --help usage: cloud-init [-h] [--version] [--file FILES] + [--debug] [--force] {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status} ... @@ -88,7 +89,7 @@ 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 +.. code-block:: shell-session % cloud-init features NETWORK_CONFIG_V1 @@ -100,10 +101,11 @@ cloud-init status ----------------- Report whether cloud-init is running, done, disabled or errored. Exits non-zero if an error is detected in cloud-init. + * **--long**: Detailed status information. * **--wait**: Block until cloud-init completes. -.. code-block:: bash +.. code-block:: shell-session % cloud-init status --long status: done @@ -214,7 +216,7 @@ of once-per-instance: * **--frequency**: Optionally override the declared module frequency with one of (always|once-per-instance|once) -.. code-block:: bash +.. code-block:: shell-session % cloud-init single --name set_hostname --frequency always diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst index c2b47edc..cacc8a27 100644 --- a/doc/rtd/topics/debugging.rst +++ b/doc/rtd/topics/debugging.rst @@ -1,6 +1,6 @@ -********************** +******************************** Testing and debugging cloud-init -********************** +******************************** Overview ======== @@ -10,7 +10,7 @@ deployed instances. .. _boot_time_analysis: 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. @@ -22,9 +22,9 @@ 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. + include each sub-stage granularity with time delta reports. -.. code-block:: bash +.. code-block:: shell-session $ cloud-init analyze show -i my-cloud-init.log -- Boot Record 01 -- @@ -41,9 +41,9 @@ include each sub-stage granularity with time delta reports. * ``analyze dump`` Parse cloud-init.log into event records and return a list of -dictionaries that can be consumed for other reporting needs. + dictionaries that can be consumed for other reporting needs. -.. code-block:: bash +.. code-block:: shell-session $ cloud-init analyze blame -i my-cloud-init.log [ @@ -56,10 +56,10 @@ dictionaries that can be consumed for other reporting needs. },... * ``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. + on highest time cost for quick assessment of areas of cloud-init that may + need improvement. -.. code-block:: bash +.. code-block:: shell-session $ cloud-init analyze blame -i my-cloud-init.log -- Boot Record 11 -- @@ -73,31 +73,36 @@ Analyze quickstart - LXC --------------------------- To quickly obtain a cloud-init log try using lxc on any ubuntu system: -.. code-block:: bash +.. code-block:: shell-session + + $ 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 - - $ 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 + +.. code-block:: shell-session + + $ 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 +.. code-block:: shell-session $ 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 +.. code-block:: shell-session $ cat > user-data <<EOF #cloud-config @@ -108,18 +113,18 @@ To quickly analyze a KVM a cloud-init log: 4. Launch your modified VM -.. code-block:: bash +.. code-block:: shell-session $ 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 + -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 +.. code-block:: shell-session $ ssh -p 2222 ubuntu@localhost 'cat /var/log/cloud-init.log' | \ - cloud-init analyze blame -i - + cloud-init analyze blame -i - Running single cloud config modules @@ -136,7 +141,7 @@ 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 +.. code-block:: shell-session $ sudo cloud-init single --name cc_ssh --frequency always ... diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst index 96c1cf59..1e994551 100644 --- a/doc/rtd/topics/network-config.rst +++ b/doc/rtd/topics/network-config.rst @@ -202,7 +202,7 @@ is helpful for examining expected output for a given input format. CLI Interface : -.. code-block:: bash +.. code-block:: shell-session % tools/net-convert.py --help usage: net-convert.py [-h] --network-data PATH --kind @@ -222,7 +222,7 @@ CLI Interface : Example output converting V2 to sysconfig: -.. code-block:: bash +.. code-block:: shell-session % tools/net-convert.py --network-data v2.yaml --kind yaml \ --output-kind sysconfig -d target diff --git a/doc/rtd/topics/tests.rst b/doc/rtd/topics/tests.rst index bf04bb3c..cac4a6e4 100644 --- a/doc/rtd/topics/tests.rst +++ b/doc/rtd/topics/tests.rst @@ -21,7 +21,7 @@ Overview In order to avoid the need for dependencies and ease the setup and configuration users can run the integration tests via tox: -.. code-block:: bash +.. code-block:: shell-session $ git clone https://git.launchpad.net/cloud-init $ cd cloud-init @@ -51,7 +51,7 @@ The first example will provide a complete end-to-end run of data collection and verification. There are additional examples below explaining how to run one or the other independently. -.. code-block:: bash +.. code-block:: shell-session $ git clone https://git.launchpad.net/cloud-init $ cd cloud-init @@ -93,7 +93,7 @@ If developing tests it may be necessary to see if cloud-config works as expected and the correct files are pulled down. In this case only a collect can be ran by running: -.. code-block:: bash +.. code-block:: shell-session $ tox -e citest -- collect -n xenial --data-dir /tmp/collection @@ -106,7 +106,7 @@ Verify When developing tests it is much easier to simply rerun the verify scripts without the more lengthy collect process. This can be done by running: -.. code-block:: bash +.. code-block:: shell-session $ tox -e citest -- verify --data-dir /tmp/collection @@ -133,7 +133,7 @@ cloud-init deb from or use the ``tree_run`` command using a copy of cloud-init located in a different directory, use the option ``--cloud-init /path/to/cloud-init``. -.. code-block:: bash +.. code-block:: shell-session $ tox -e citest -- tree_run --verbose \ --os-name xenial --os-name stretch \ @@ -331,7 +331,7 @@ Integration tests are located under the `tests/cloud_tests` directory. Test configurations are placed under `configs` and the test verification scripts under `testcases`: -.. code-block:: bash +.. code-block:: shell-session cloud-init$ tree -d tests/cloud_tests/ tests/cloud_tests/ @@ -362,7 +362,7 @@ The following would create a test case named ``example`` under the ``modules`` category with the given description, and cloud config data read in from ``/tmp/user_data``. -.. code-block:: bash +.. code-block:: shell-session $ tox -e citest -- create modules/example \ -d "a simple example test case" -c "$(< /tmp/user_data)" @@ -385,7 +385,7 @@ Development Checklist * Placed in the appropriate sub-folder in the test cases directory * Tested by running the test: - .. code-block:: bash + .. code-block:: shell-session $ tox -e citest -- run -verbose \ --os-name <release target> \ @@ -404,14 +404,14 @@ These configuration files are the standard that the AWS cli and other AWS tools utilize for interacting directly with AWS itself and are normally generated when running ``aws configure``: -.. code-block:: bash +.. code-block:: shell-session $ cat $HOME/.aws/credentials [default] aws_access_key_id = <KEY HERE> aws_secret_access_key = <KEY HERE> -.. code-block:: bash +.. code-block:: shell-session $ cat $HOME/.aws/config [default] |