From c0d0c1d93eceec430f8c4a70791293318a993e7c Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Fri, 11 Mar 2022 12:22:23 -0700 Subject: [PATCH 1/7] remove headers of missing examples --- doc/rtd/topics/examples.rst | 21 --------------------- 1 file changed, 21 deletions(-) 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 ============================ From 27b07f53c3ad178bef857c77b4ccb049d9fc0251 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Fri, 11 Mar 2022 12:29:25 -0700 Subject: [PATCH 2/7] Security docs aren't rendered, fix it. - m2r seems abandoned, switch to m2r2 - fix rst to actually render the security page --- doc-requirements.txt | 5 ++--- doc/rtd/conf.py | 4 ++-- doc/rtd/topics/security.rst | 5 +++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc-requirements.txt b/doc-requirements.txt index 387ebe9dab1..80315e7cab2 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -1,10 +1,9 @@ doc8 -m2r -sphinx<2 +m2r2 +sphinx sphinx_rtd_theme pyyaml # 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 diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 9976afa44a8..0211f0a054c 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -23,12 +23,12 @@ # -- 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.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinx.ext.viewcode", 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 From bba044862280ecd8336e5cbdd13a20ba5539ef20 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Fri, 11 Mar 2022 12:35:13 -0700 Subject: [PATCH 3/7] UX nit: put deprecated content in a drop-down panel --- doc-requirements.txt | 1 + doc/rtd/conf.py | 3 +- doc/rtd/topics/datasources/configdrive.rst | 48 +++++++++++----------- 3 files changed, 28 insertions(+), 24 deletions(-) diff --git a/doc-requirements.txt b/doc-requirements.txt index 80315e7cab2..63f62725cd7 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -3,6 +3,7 @@ m2r2 sphinx sphinx_rtd_theme pyyaml +sphinx-panels # Indirect dependencies jinja2<3.1.0 # https://github.com/readthedocs/readthedocs.org/issues/9037 diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 0211f0a054c..5559f0fa087 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -23,12 +23,13 @@ # -- General configuration ---------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '4.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 = [ "m2r2", + "sphinx_panels", "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinx.ext.viewcode", 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 --------- From 080d709f8785ce2705e8f67abddbdea0f2d51e19 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Wed, 16 Mar 2022 09:51:02 -0600 Subject: [PATCH 4/7] Nits in wording regarding security - Implying a cryptographic hash function is "safe" generally doesn't age well. - Linux users are likely to require escalating privileges on the host as part of system administration. Therefore, telling users to "only use ssh, not passwords" is likely to be interpreted as one of the following: - log in as root via ssh [1] - log in as a user that has passwordless sudo access [1] Both of these interpretations go against security best practices. Rather than giving security advice, warn of the risks associated with the feature and let users make their own decisions. [1] using an auth method such as ssh keys --- doc/examples/cloud-config-user-groups.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) 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. From dd54b7642723bafad76303125054408f191a7123 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Mon, 28 Mar 2022 09:32:13 -0600 Subject: [PATCH 5/7] RST link/ref is broken, fix it. --- doc/rtd/topics/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From e7d1427e8af80d86c255b5363cd40fbdb6054bcf Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Mon, 28 Mar 2022 09:55:44 -0600 Subject: [PATCH 6/7] include rtd_theme as extension, per https://sphinx-rtd-theme.readthedocs.io/en/stable/installing.html --- doc-requirements.txt | 6 +++--- doc/rtd/conf.py | 3 +++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc-requirements.txt b/doc-requirements.txt index 63f62725cd7..38c943e1df2 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -1,10 +1,10 @@ doc8 m2r2 -sphinx -sphinx_rtd_theme +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 +docutils==0.16 # https://github.com/readthedocs/sphinx_rtd_theme/issues/1115 diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index 5559f0fa087..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, @@ -29,6 +31,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ "m2r2", + "sphinx_rtd_theme", "sphinx_panels", "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", From ba95870e6f5deb473fc9d44df98405c7a258b2a0 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Mon, 28 Mar 2022 11:46:43 -0600 Subject: [PATCH 7/7] Code in italics get rendered incorrectly in newer sphinx, fix it They looked funny italicized currently, switch to inline codeblock. --- doc/rtd/topics/cli.rst | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) 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