diff --git a/doc-requirements.txt b/doc-requirements.txt index 387ebe9dab1..38c943e1df2 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -1,10 +1,10 @@ doc8 -m2r -sphinx<2 -sphinx_rtd_theme +m2r2 +sphinx==4.3.0 +sphinx_rtd_theme==1.0.0 pyyaml +sphinx-panels # Indirect dependencies jinja2<3.1.0 # https://github.com/readthedocs/readthedocs.org/issues/9037 -docutils<0.18 -mistune<2.0.0 # https://github.com/miyakogi/m2r/issues/66 +docutils==0.16 # https://github.com/readthedocs/sphinx_rtd_theme/issues/1115 diff --git a/doc/examples/cloud-config-user-groups.txt b/doc/examples/cloud-config-user-groups.txt index eaa8dd241c1..f8fb3f9265a 100644 --- a/doc/examples/cloud-config-user-groups.txt +++ b/doc/examples/cloud-config-user-groups.txt @@ -64,7 +64,7 @@ users: # lock_passwd: Defaults to true. Lock the password to disable password login # inactive: Number of days after password expires until account is disabled # passwd: The hash -- not the password itself -- of the password you want -# to use for this user. You can generate a safe hash via: +# to use for this user. You can generate a hash via: # mkpasswd --method=SHA-512 --rounds=4096 # (the above command would create from stdin an SHA-512 password hash # with 4096 salt rounds) @@ -81,9 +81,8 @@ users: # In other words, this feature is a potential security risk and is # provided for your convenience only. If you do not fully trust the # medium over which your cloud-config will be transmitted, then you -# should use SSH authentication only. +# should not use this feature. # -# You have thus been warned. # no_create_home: When set to true, do not create home directory. # no_user_group: When set to true, do not create a group named after the user. # no_log_init: When set to true, do not initialize lastlog and faillog database. diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 9976afa44a8..c80c23f3aa9 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -1,6 +1,8 @@ import os import sys +import sphinx_rtd_theme + from cloudinit import version # If extensions (or modules to document with autodoc) are in another directory, @@ -23,12 +25,14 @@ # -- General configuration ---------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' +needs_sphinx = "4.0" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ - "m2r", + "m2r2", + "sphinx_rtd_theme", + "sphinx_panels", "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinx.ext.viewcode", diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst index e2f48bf0ade..e90706fcab4 100644 --- a/doc/rtd/topics/cli.rst +++ b/doc/rtd/topics/cli.rst @@ -66,8 +66,8 @@ clean Remove cloud-init artifacts from ``/var/lib/cloud`` to simulate a clean instance. On reboot, cloud-init will re-run all stages as it did on first boot. -* *\\-\\-logs*: optionally remove all cloud-init log files in ``/var/log/`` -* *\\-\\-reboot*: reboot the system after removing artifacts +* ``--logs``: optionally remove all cloud-init log files in ``/var/log/`` +* ``--reboot``: reboot the system after removing artifacts .. _cli_collect_logs: @@ -152,7 +152,7 @@ Can be run on the commandline, but is generally gated to run only once due to semaphores in ``/var/lib/cloud/instance/sem/`` and ``/var/lib/cloud/sem``. -* *\\-\\-local*: run *init-local* stage instead of *init* +* ``--local``: run *init-local* stage instead of *init* .. _cli_modules: @@ -173,8 +173,8 @@ declared to run in various boot stages in the file Can be run on the command line, but each module is gated to run only once due to semaphores in ``/var/lib/cloud/``. -* *\\-\\-mode [init|config|final]*: run *modules:init*, *modules:config* or - *modules:final* cloud-init stages. See :ref:`boot_stages` for more info. +* ``--mode [init|config|final]``: run ``modules:init``, ``modules:config`` or + `modules:final` cloud-init stages. See :ref:`boot_stages` for more info. .. _cli_query: @@ -187,13 +187,13 @@ in ``/run/cloud-init/instance-data.json``. This is a convenience command-line interface to reference any cached configuration metadata that cloud-init crawls when booting the instance. See :ref:`instance_metadata` for more info. -* *\\-\\-all*: dump all available instance data as json which can be queried -* *\\-\\-instance-data*: optional path to a different instance-data.json file +* ``--all``: dump all available instance data as json which can be queried +* ``--instance-data``: optional path to a different instance-data.json file to source for queries -* *\\-\\-list-keys*: list available query keys from cached instance data -* *\\-\\-format*: a string that will use jinja-template syntax to render a +* ``--list-keys``: list available query keys from cached instance data +* ``--format``: a string that will use jinja-template syntax to render a string replacing -* **: a dot-delimited variable path into the instance-data.json +* ````: a dot-delimited variable path into the instance-data.json object Below demonstrates how to list all top-level query keys that are standardized @@ -256,8 +256,8 @@ single Attempt to run a single named cloud config module. -* *\\-\\-name*: the cloud-config module name to run -* *\\-\\-frequency*: optionally override the declared module frequency +* ``--name``: the cloud-config module name to run +* ``--frequency``: optionally override the declared module frequency with one of (always|once-per-instance|once) The following example re-runs the cc_set_hostname module ignoring the module @@ -281,8 +281,8 @@ 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 +* ``--long``: detailed status information +* ``--wait``: block until cloud-init completes Below are examples of output when cloud-init is running, showing status and the currently running modules, as well as when it is done. @@ -306,5 +306,3 @@ the currently running modules, as well as when it is done. time: Wed, 17 Jan 2018 20:41:59 +0000 detail: DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net] - -.. vi: textwidth=79 diff --git a/doc/rtd/topics/datasources/configdrive.rst b/doc/rtd/topics/datasources/configdrive.rst index ca18c64077e..777597c2757 100644 --- a/doc/rtd/topics/datasources/configdrive.rst +++ b/doc/rtd/topics/datasources/configdrive.rst @@ -18,39 +18,41 @@ case then the files contained on the located drive must provide equivalents to what the EC2 metadata service would provide (which is typical of the version 2 support listed below) -Version 1 ---------- -**Note:** Version 1 is legacy and should be considered deprecated. Version 2 -has been supported in OpenStack since 2012.2 (Folsom). +.. dropdown:: Version 1 (Deprecated) -The following criteria are required to as a config drive: + **Note:** Version 1 is legacy and should be considered deprecated. + Version 2 has been supported in OpenStack since 2012.2 (Folsom). -1. Must be formatted with `vfat`_ filesystem -2. Must contain *one* of the following files + The following criteria are required to as a config drive: -:: + 1. Must be formatted with `vfat`_ filesystem + 2. Must contain *one* of the following files + + :: + + /etc/network/interfaces + /root/.ssh/authorized_keys + /meta.js - /etc/network/interfaces - /root/.ssh/authorized_keys - /meta.js + ``/etc/network/interfaces`` -``/etc/network/interfaces`` + This file is laid down by nova in order to pass static networking + information to the guest. Cloud-init will copy it off of the + config-drive and into /etc/network/interfaces (or convert it to RH + format) as soon as it can, and then attempt to bring up all network + interfaces. - This file is laid down by nova in order to pass static networking - information to the guest. Cloud-init will copy it off of the config-drive - and into /etc/network/interfaces (or convert it to RH format) as soon as - it can, and then attempt to bring up all network interfaces. + ``/root/.ssh/authorized_keys`` -``/root/.ssh/authorized_keys`` + This file is laid down by nova, and contains the ssk keys that were + provided to nova on instance creation (nova-boot --key ....) - This file is laid down by nova, and contains the ssk keys that were - provided to nova on instance creation (nova-boot --key ....) + ``/meta.js`` -``/meta.js`` + meta.js is populated on the config-drive in response to the user + passing "meta flags" (nova boot --meta key=value ...). It is + expected to be json formatted. - meta.js is populated on the config-drive in response to the user passing - "meta flags" (nova boot --meta key=value ...). It is expected to be json - formatted. Version 2 --------- diff --git a/doc/rtd/topics/examples.rst b/doc/rtd/topics/examples.rst index a07269a9286..f681f37b731 100644 --- a/doc/rtd/topics/examples.rst +++ b/doc/rtd/topics/examples.rst @@ -41,13 +41,6 @@ Install and run `chef`_ recipes :language: yaml :linenos: -Setup and run `puppet`_ -======================= - -.. literalinclude:: ../../examples/cloud-config-puppet.txt - :language: yaml - :linenos: - Add primary apt repositories ============================ @@ -102,20 +95,6 @@ Adjust mount points mounted :language: yaml :linenos: -Call a url when finished -======================== - -.. literalinclude:: ../../examples/cloud-config-phone-home.txt - :language: yaml - :linenos: - -Reboot/poweroff when finished -============================= - -.. literalinclude:: ../../examples/cloud-config-power-state.txt - :language: yaml - :linenos: - Configure instances SSH keys ============================ diff --git a/doc/rtd/topics/logging.rst b/doc/rtd/topics/logging.rst index a14fb6855a2..96c30b999d7 100644 --- a/doc/rtd/topics/logging.rst +++ b/doc/rtd/topics/logging.rst @@ -168,7 +168,7 @@ With defaults used:: log_serv: "10.0.4.1" -For more information on rsyslog configuration, see :ref:`cc_rsyslog`. +For more information on rsyslog configuration, see :ref:`rsyslog`. .. _python logging config: https://docs.python.org/3/library/logging.config.html#configuration-file-format .. _python logging handlers: https://docs.python.org/3/library/logging.handlers.html diff --git a/doc/rtd/topics/security.rst b/doc/rtd/topics/security.rst index 48fcb0a590a..ad934ded0ac 100644 --- a/doc/rtd/topics/security.rst +++ b/doc/rtd/topics/security.rst @@ -1,5 +1,6 @@ +******** +Security +******** .. _security: .. mdinclude:: ../../../SECURITY.md - -.. vi: textwidth=79