diff --git a/.wordlist.txt b/.wordlist.txt index 4821fb19..eb7c92d1 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -205,3 +205,7 @@ virtualised CNCF AgentBaker sku +Diátaxis +reStructuredText +localhost +HTML diff --git a/aws/aws-how-to/contributions/contribute-to-these-docs.rst b/aws/aws-how-to/contributions/contribute-to-these-docs.rst new file mode 100644 index 00000000..82dcd66c --- /dev/null +++ b/aws/aws-how-to/contributions/contribute-to-these-docs.rst @@ -0,0 +1,39 @@ +Contribute to these docs +======================== + +.. include:: ../../../reuse/contribute-to-docs.txt + :start-after: Start: How to contribute + :end-before: End: How to contribute + +.. code:: + + PROJECT=aws make run + +Setting the `PROJECT` parameter to ``aws`` ensures that the documentation set for `Ubuntu on AWS` gets built. This parameter is needed to distinguish between the different documentation sets present in the repository. + +If you don't want to preview the changes continuously and only wish to build the docs once (e.g., to have a local copy on your machine), then run ``PROJECT=aws make html``. This will create the AWS related HTML pages in _build/aws. You can preview the site by opening ``index.html`` on your web browser. + + +Perform checks and submit PR +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before opening a PR, run the following checks and also ensure that the documentation builds without any warnings (warnings are treated as errors): + +.. code:: + + PROJECT=aws make spelling + PROJECT=aws make linkcheck + PROJECT=aws make woke + +If you need to add new words to the allowed list of words, include them in ``.wordlist.txt``. + +Once all the edits are done, commit the changes and push it to your fork. From the GitHub GUI of your fork, select the commit and open a PR for it. + +.. _`ubuntu-cloud-docs`: https://github.com/canonical/ubuntu-cloud-docs +.. _`Diátaxis`: https://diataxis.fr/ +.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html +.. _`Canonical style guide`: https://docs.ubuntu.com/styleguide/en +.. _`Sphinx`: https://www.sphinx-doc.org/en/master/ +.. _`Read the Docs`: https://readthedocs.com + + diff --git a/aws/aws-how-to/contributions/index.rst b/aws/aws-how-to/contributions/index.rst new file mode 100644 index 00000000..5695bfa2 --- /dev/null +++ b/aws/aws-how-to/contributions/index.rst @@ -0,0 +1,9 @@ +Contributions +============= + + +.. toctree:: + :maxdepth: 1 + + contribute-to-these-docs + \ No newline at end of file diff --git a/aws/aws-how-to/index.rst b/aws/aws-how-to/index.rst index c5dd68b5..3f0b8bed 100644 --- a/aws/aws-how-to/index.rst +++ b/aws/aws-how-to/index.rst @@ -1,39 +1,35 @@ How-to guides ============= -If you want to find the right Ubuntu image, upgrade from Ubuntu 20.04 to 22.04, create CloudFormation templates, automatically update your Ubuntu instances, or just launch an Ubuntu desktop on EC2, refer to these guides: +Launching and using Ubuntu instances: -* :doc:`./find-ubuntu-images` -* :doc:`./upgrade-from-focal-to-jammy` -* :doc:`./build-cloudformation-templates` -* :doc:`./automatically-update-ubuntu-instances` -* :doc:`./launch-ubuntu-desktop` +* :doc:`instances/find-ubuntu-images` +* :doc:`instances/build-pro-ami-using-packer` +* :doc:`instances/build-cloudformation-templates` +* :doc:`instances/launch-ubuntu-desktop` +* :doc:`instances/automatically-update-ubuntu-instances` +* :doc:`instances/upgrade-from-focal-to-jammy` -Ubuntu Pro related user guides: +Using Kubernetes: -* :doc:`./build-pro-ami-using-packer` -* :doc:`./deploy-ubuntu-pro-cluster` -* :doc:`./deploy-charmed-kubernetes-on-ubuntu-pro` +* :doc:`kubernetes/deploy-ubuntu-pro-cluster` +* :doc:`kubernetes/enable-gpus-on-eks` +* :doc:`kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro` -Finally, if you want to use UEFI Secure Boot or enable GPUs on EKS worker nodes, use: +Security: -* :doc:`./use-secureboot-and-vtpm` -* :doc:`./enable-gpus-on-eks` +* :doc:`security/use-secureboot-and-vtpm` +Contributions: + +* :doc:`contributions/contribute-to-these-docs` .. toctree:: :hidden: :maxdepth: 1 - find-ubuntu-images - upgrade-from-focal-to-jammy - build-cloudformation-templates - automatically-update-ubuntu-instances - launch-ubuntu-desktop - - build-pro-ami-using-packer - deploy-ubuntu-pro-cluster - deploy-charmed-kubernetes-on-ubuntu-pro - - use-secureboot-and-vtpm - enable-gpus-on-eks \ No newline at end of file + instances/index + kubernetes/index + security/index + contributions/index + \ No newline at end of file diff --git a/aws/aws-how-to/automatically-update-ubuntu-instances-images/schedule_task.png b/aws/aws-how-to/instances/automatically-update-ubuntu-instances-images/schedule_task.png similarity index 100% rename from aws/aws-how-to/automatically-update-ubuntu-instances-images/schedule_task.png rename to aws/aws-how-to/instances/automatically-update-ubuntu-instances-images/schedule_task.png diff --git a/aws/aws-how-to/automatically-update-ubuntu-instances.rst b/aws/aws-how-to/instances/automatically-update-ubuntu-instances.rst similarity index 100% rename from aws/aws-how-to/automatically-update-ubuntu-instances.rst rename to aws/aws-how-to/instances/automatically-update-ubuntu-instances.rst diff --git a/aws/aws-how-to/aws-marketplace-identifiers.csv b/aws/aws-how-to/instances/aws-marketplace-identifiers.csv similarity index 100% rename from aws/aws-how-to/aws-marketplace-identifiers.csv rename to aws/aws-how-to/instances/aws-marketplace-identifiers.csv diff --git a/aws/aws-how-to/build-cloudformation-templates.rst b/aws/aws-how-to/instances/build-cloudformation-templates.rst similarity index 100% rename from aws/aws-how-to/build-cloudformation-templates.rst rename to aws/aws-how-to/instances/build-cloudformation-templates.rst diff --git a/aws/aws-how-to/build-pro-ami-using-packer.rst b/aws/aws-how-to/instances/build-pro-ami-using-packer.rst similarity index 100% rename from aws/aws-how-to/build-pro-ami-using-packer.rst rename to aws/aws-how-to/instances/build-pro-ami-using-packer.rst diff --git a/aws/aws-how-to/find-ubuntu-images.rst b/aws/aws-how-to/instances/find-ubuntu-images.rst similarity index 100% rename from aws/aws-how-to/find-ubuntu-images.rst rename to aws/aws-how-to/instances/find-ubuntu-images.rst diff --git a/aws/aws-how-to/instances/index.rst b/aws/aws-how-to/instances/index.rst new file mode 100644 index 00000000..2dbbfa9a --- /dev/null +++ b/aws/aws-how-to/instances/index.rst @@ -0,0 +1,12 @@ +EC2 instances +============= + +.. toctree:: + :maxdepth: 1 + + find-ubuntu-images + build-pro-ami-using-packer + build-cloudformation-templates + launch-ubuntu-desktop + automatically-update-ubuntu-instances + upgrade-from-focal-to-jammy diff --git a/aws/aws-how-to/launch-ubuntu-desktop.rst b/aws/aws-how-to/instances/launch-ubuntu-desktop.rst similarity index 100% rename from aws/aws-how-to/launch-ubuntu-desktop.rst rename to aws/aws-how-to/instances/launch-ubuntu-desktop.rst diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/0_additional_ssh_daemon.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/0_additional_ssh_daemon.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/0_additional_ssh_daemon.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/0_additional_ssh_daemon.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/1_firewall_for_additional_ssh.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/1_firewall_for_additional_ssh.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/1_firewall_for_additional_ssh.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/1_firewall_for_additional_ssh.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/2_start_upgrade.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/2_start_upgrade.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/2_start_upgrade.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/2_start_upgrade.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/3_restart_services.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/3_restart_services.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/3_restart_services.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/3_restart_services.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/4_sshd_modified_config.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/4_sshd_modified_config.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/4_sshd_modified_config.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/4_sshd_modified_config.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/5_remove_obsolete.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/5_remove_obsolete.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/5_remove_obsolete.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/5_remove_obsolete.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy-images/6_finish_upgrade.png b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/6_finish_upgrade.png similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy-images/6_finish_upgrade.png rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy-images/6_finish_upgrade.png diff --git a/aws/aws-how-to/upgrade-from-focal-to-jammy.rst b/aws/aws-how-to/instances/upgrade-from-focal-to-jammy.rst similarity index 100% rename from aws/aws-how-to/upgrade-from-focal-to-jammy.rst rename to aws/aws-how-to/instances/upgrade-from-focal-to-jammy.rst diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/1_user_details.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/1_user_details.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/1_user_details.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/1_user_details.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/2_create_user.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/2_create_user.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/2_create_user.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/2_create_user.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/3_retrieve_access_keys.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/3_retrieve_access_keys.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/3_retrieve_access_keys.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/3_retrieve_access_keys.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/4_get_pro_ami_id.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/4_get_pro_ami_id.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/4_get_pro_ami_id.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/4_get_pro_ami_id.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/5_check_deployment_status.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/5_check_deployment_status.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/5_check_deployment_status.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/5_check_deployment_status.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/6_deployment_status_on_EC2.jpg b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/6_deployment_status_on_EC2.jpg similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro-images/6_deployment_status_on_EC2.jpg rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro-images/6_deployment_status_on_EC2.jpg diff --git a/aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro.rst b/aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro.rst similarity index 100% rename from aws/aws-how-to/deploy-charmed-kubernetes-on-ubuntu-pro.rst rename to aws/aws-how-to/kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro.rst diff --git a/aws/aws-how-to/deploy-ubuntu-pro-cluster.rst b/aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst similarity index 98% rename from aws/aws-how-to/deploy-ubuntu-pro-cluster.rst rename to aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst index 094ca7a9..53df5460 100644 --- a/aws/aws-how-to/deploy-ubuntu-pro-cluster.rst +++ b/aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst @@ -26,7 +26,7 @@ The steps needed for deploying the cluster depend on whether you need to enable .. tabs:: - .. tab:: Without FIPS + .. group-tab:: Without FIPS When FIPS is not enabled, you can use one of the existing Ubuntu EKS AMIs and customise it using cloud-init's `ubuntu-advantage module `_ during deployment. @@ -61,7 +61,7 @@ The steps needed for deploying the cluster depend on whether you need to enable Cloud-init will use this user-data to enable ESM on the cluster nodes and bootstrap the AWS EKS cluster. - .. tab:: With FIPS + .. group-tab:: With FIPS When enabling FIPS, a reboot of the underlying node is required. If this reboot is done after the cluster is created, in rare cases, it might result in the node being flagged as defective (`troubleshooting options `_). For this reason, the most reliable way to deploy an Ubuntu Pro EKS cluster is to build a custom Ubuntu Pro AMI (with `Packer `_) and use it during cluster creation until this `issue `_ is resolved. @@ -184,7 +184,7 @@ Add the following content to your file .. tabs:: - .. tab:: Without FIPS + .. group-tab:: Without FIPS .. code-block:: yaml @@ -198,7 +198,7 @@ Add the following content to your file This config file will allow you to create an EKS cluster using the launch template from above, with two nodes. - .. tab:: With FIPS + .. group-tab:: With FIPS .. code-block:: yaml diff --git a/aws/aws-how-to/enable-gpus-on-eks.rst b/aws/aws-how-to/kubernetes/enable-gpus-on-eks.rst similarity index 100% rename from aws/aws-how-to/enable-gpus-on-eks.rst rename to aws/aws-how-to/kubernetes/enable-gpus-on-eks.rst diff --git a/aws/aws-how-to/kubernetes/index.rst b/aws/aws-how-to/kubernetes/index.rst new file mode 100644 index 00000000..b395bdfd --- /dev/null +++ b/aws/aws-how-to/kubernetes/index.rst @@ -0,0 +1,9 @@ +EKS and Charmed Kubernetes +========================== + +.. toctree:: + :maxdepth: 1 + + deploy-ubuntu-pro-cluster + enable-gpus-on-eks + deploy-charmed-kubernetes-on-ubuntu-pro \ No newline at end of file diff --git a/aws/aws-how-to/security/index.rst b/aws/aws-how-to/security/index.rst new file mode 100644 index 00000000..bbd5462d --- /dev/null +++ b/aws/aws-how-to/security/index.rst @@ -0,0 +1,7 @@ +Security features +================= + +.. toctree:: + :maxdepth: 1 + + use-secureboot-and-vtpm diff --git a/aws/aws-how-to/use-secureboot-and-vtpm.rst b/aws/aws-how-to/security/use-secureboot-and-vtpm.rst similarity index 100% rename from aws/aws-how-to/use-secureboot-and-vtpm.rst rename to aws/aws-how-to/security/use-secureboot-and-vtpm.rst diff --git a/aws/index.rst b/aws/index.rst index 9c585d98..ee1ac5e3 100644 --- a/aws/index.rst +++ b/aws/index.rst @@ -43,11 +43,12 @@ suggestions, fixes and constructive feedback. * `Get support`_ * `Join our online chat`_ * `Talk to us about Ubuntu on AWS`_ +* :doc:`aws-how-to/contributions/contribute-to-these-docs` .. toctree:: :hidden: - :maxdepth: 2 + :maxdepth: 1 aws-how-to/index aws-explanation/index diff --git a/reuse/common-intro.txt b/reuse/common-intro.txt index fd33b76b..73c734e6 100644 --- a/reuse/common-intro.txt +++ b/reuse/common-intro.txt @@ -49,3 +49,5 @@ End: Daily vs release images ============================================================== + + diff --git a/reuse/contribute-to-docs.txt b/reuse/contribute-to-docs.txt new file mode 100644 index 00000000..489b000b --- /dev/null +++ b/reuse/contribute-to-docs.txt @@ -0,0 +1,52 @@ +============================================================== + +Start: How to contribute + +These docs are on located on a GitHub repository at: `ubuntu-cloud-docs`_ and you'll need a GitHub account to make contributions. The docs are: + + * structured using the `Diátaxis`_ approach, + * written in `reStructuredText`_ as per the `Canonical style guide`_, + * built with `Sphinx`_ and + * hosted on `Read the Docs`_. + +We are always looking for ways to improve our docs, so we appreciate your contributions! + +Minor changes +------------- + +If you've found a problem that can be fixed with a small change, you can use the pencil icon at the top of the relevant page to edit it on GitHub. When you are done with your edits, select :guilabel:`Commit changes...` on the top right. This will help you create a new branch and start a pull request (PR). Use :guilabel:`Propose changes` to submit the PR. We will review it and merge the changes. + + +Suggestions and questions +------------------------- + +Use the :guilabel:`Give feedback` button at the top of any page to create a GitHub issue for any suggestions or questions that you might have. + + +New content +----------- + +While contributing new content, it is easier to work with the docs on your local machine. You can submit a PR after all the checks have passed and things looks satisfactory. + +Download and install the docs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are working with these docs for the first time, you'll need to fork and clone the `ubuntu-cloud-docs`_ repository to your local machine. Once cloned, go into the ubuntu-cloud-docs directory and run: + +.. code:: + + make install + +This creates a virtual environment and installs all the dependencies specified in ``.sphinx/requirements.txt``. You only have to do this once (unless you run a ``make clean`` sometime), and can skip this step the next time you want to contribute. + + +Build and serve the docs +~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``make run`` command to build and serve the docs at `127.0.0.1:8000 `_ or equivalently at `localhost:8000 `_. This gives you a live preview of the changes that you make (and save), without the need for a rebuild: + + +End: How to contribute + +============================================================== +