Merge "Update site set up and authoring guide for release v2.1"

2021-11-17 20:34:42 +00:00 · 2021-11-17 20:34:42 +00:00 · 3217a175bb
commit 3217a175bb
parent 2c265a5b42 1e0a9200ee
2 changed files with 56 additions and 37 deletions
--- a/doc/source/airship2/site-authoring.rst
+++ b/doc/source/airship2/site-authoring.rst
@ -55,7 +55,7 @@ testing of Airship on bare metal.
 To create a new site definition from the ``reference-airship-core`` site, the
 following steps are required:

-1. Clone the ``treasuremap`` repository at the specified reference in the Airship
+1. Clone or checkout the ``treasuremap`` repository at the specified reference in the Airship
   home directory.
 2. Create a project side-by-side with ``airshipctl`` and ``treasuremap`` directory.
 3. Copy the reference site manifests to ${PROJECT}/manifests/site/${SITE}.
@ -69,9 +69,9 @@ tasks.
 .. code-block:: bash

   export AIRSHIPCTL_REF_TYPE=tag # type can be "tag", "branch" or "commithash"
-   export AIRSHIPCTL_REF=v2.0.0 # update with the git ref you want to use
+   export AIRSHIPCTL_REF=v2.1.0 # update with the git ref you want to use
   export TREASUREMAP_REF_TYPE=tag # type can be "tag", "branch" or "commithash"
-   export TREASUREMAP_REF=v2.0.0 # update with the git ref you want to use
+   export TREASUREMAP_REF=v2.1.0 # update with the git ref you want to use
   export REFERENCE_SITE=../treasuremap/manifests/site/reference-airship-core
   export REFERENCE_TYPE=airship-core # the manifest type the reference site uses

@ -79,17 +79,17 @@ tasks.

 .. note::
   The environment variables have default values that point to airshipctl
-   release tag v2.0.0 and treasuremap release tag v2.0.0. You only need
+   release tag v2.1.0 and treasuremap release tag v2.1.0. You only need
   to (re)set them in the command line if you want a different release
   version, a branch or a specific commit.

   To find the Airship release versions and tags, go to :ref:`versioning`. In
-   addition to release tag, the user can also specify a branch (e.g., v2.0)
+   addition to release tag, the user can also specify a branch (e.g., v2.1)
   or a specific commit ID when checking out the ``treasuremap`` or ``airshipctl``
   repository.

 .. _reference-airship-core:
-   https://github.com/airshipit/treasuremap/tree/v2.0/manifests/site/reference-airship-core
+   https://github.com/airshipit/treasuremap/tree/v2.1/manifests/site/reference-airship-core

 Preparing Deployment Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -132,19 +132,19 @@ Before you start, collect the following network information:

 First, define the target and ephemeral networking catalogues.

-   * ``manifests/site/${SITE}/target/catalogues/networking.yaml``:
+   * ``manifests/site/${SITE}/target/catalogues/shareable/networking.yaml``:
     Contains the network definition in the entire system.
-   * ``manifests/site/${SITE}/target/catalogues/networking-ha.yaml``:
+   * ``manifests/site/${SITE}/target/catalogues/shareable/networking-ha.yaml``:
     Defines the Kubernetes and ingress virtual IP addresses as well as the
     OAM interface.
-   * ``manifests/site/${SITE}/ephemeral/catalogues/networking.yaml``:
+   * ``manifests/site/${SITE}/ephemeral/catalogues/shareable/networking.yaml``:
     Provides only the overrides specific to the ephemeral nodes.

 Last, update network references (e.g., interface name, IP address, port) in
 the target cluster deployment documents:

   * ``manifests/site/${SITE}/phases/phase-patch.yaml``
-   * ``manifests/site/${SITE}/target/catalogues/versions-airshipctl.yaml``
+   * ``manifests/site/${SITE}/target/catalogues/shareable/versions-airshipctl.yaml``
   * ``manifests/site/${SITE}/target/controlplane/metal3machinetemplate.yaml``
   * ``manifests/site/${SITE}/target/controlplane/versions-catalogue-patch.yaml``
   * ``manifests/site/${SITE}/target/initinfra-networking/patch_calico.yaml``
@ -166,7 +166,7 @@ Update the host inventory and other ephemeral and target cluster documents:

   * ``manifests/site/${SITE}/host-inventory/hostgenerator/host-generation.yaml``:
     Lists the host names of the all the nodes in the host inventory.
-   * ``manifests/site/${SITE}/target/catalogues/hosts.yaml``: The host catalogue
+   * ``manifests/site/${SITE}/target/catalogues/shareable/hosts.yaml``: The host catalogue
     defines the host information such as BMC address, credential, PXE NIC, IP
     addresses, hardware profile name, etc., for every single host.
   * ``manifests/site/${SITE}/ephemeral/bootstrap/baremetalhost.yaml``:
@ -179,11 +179,31 @@ Update the host inventory and other ephemeral and target cluster documents:
   * ``manifests/site/${SITE}/phases/phase-patch.yaml``: Updates the ephemeral
     node host name and ISO URL.
   * ``manifests/site/${SITE}/target/controlplane/hostgenerator/host-generation.yaml``:
-     Defines the list of hosts to be deployed in the target cluster.
+     Defines the list of hosts to be deployed in the target cluster control plane.
   * ``manifests/site/${SITE}/target/workers/hostgenerator/host-generation.yaml``:
     Defines the list of hosts of the worker nodes.
-   * ``manifests/site/air-pod01/target/workers/provision/machinedeployment.yaml``:
-     Configures the total number of worker nodes
+   * ``manifests/site/${SITE}/target/workers/provision/machinedeployment.yaml``:
+     Configures the total number of worker nodes.
+
+Storage
+++++++
+
+Using a general purpose `Ceph cluster configuration`_ in Treasuremap manifests,
+Rook will deploy Ceph cluster using all the remaining disks, i.e., raw devices
+with no partitions or formatted filesystems, on all the hosts (both controller
+and worker nodes).
+
+The user can customize the Ceph cluster configuration based on specific use
+cases. The following is an example to specify which hosts to include in the
+storage cluster and which devices to use for Ceph:
+
+* ``treasuremap/manifests/site/{SITE}/target/catalogues/shareable/storage.yaml``
+
+For more information, please refer to `Rook Ceph Storage <https://rook.io/docs/rook/v1.6/ceph-storage.html>`_
+document.
+
+.. _Ceph cluster configuration:
+   https://github.com/airshipit/treasuremap/blob/master/manifests/composite/storage-cluster/cephcluster.yaml#L32-L33

 Downstream Images and Binaries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- a/doc/source/airship2/site-setup.rst
+++ b/doc/source/airship2/site-setup.rst
@ -43,12 +43,12 @@ network configuration.
  deployed with very minimal requirements if needed (e.g., single disk, single
  network).

-  For simplified non-bonded, and single disk examples, see Treasuremap
+  For simplified non-bonded, and single disk examples, see Airshipctl
  `test-site`_.

-.. _reference-airship-core: https://github.com/airshipit/treasuremap/tree/v2.0/manifests/site/reference-airship-core
+.. _reference-airship-core: https://github.com/airshipit/treasuremap/tree/master/manifests/site/reference-airship-core

-.. _test-site: https://github.com/airshipit/treasuremap/tree/v2.0/manifests/site/test-site
+.. _test-site: https://github.com/airshipit/airshipctl/tree/master/manifests/site/test-site

 BIOS, Redfish and PXE
 ~~~~~~~~~~~~~~~~~~~~~
@ -81,20 +81,13 @@ Disk
   - Two-disk RAID-1: Operating System
   - Remaining disks: configuration per worker host profile

-.. note::
+3. For nodes in the storage cluster:

-   As of release v2.0.0, the ``reference-airship-core`` example does not
-   support the integration with the `Rook Storage Operator`_. However, the
-   manifests for the Rook deployment can be found in the
-   ``manifests/function/rook-operator`` directory. If you plan to include
-   Rook for Ceph storage, it is recommended to have the additional disks
-   on all the controller nodes and worker nodes:
-
-   - Two disks JBOD: Ceph Journal and Metadata
-   - Two disks JBOD: Ceph OSD's
-
-.. _Rook Storage Operator:
-    https://rook.io/
+   After the allocation of disks for the host OS and other uses, remaining
+   disks can be configured as RAID-0/JBOD for Ceph. If both SSD and HDD disks
+   are present, it is recommended to configure two Ceph clusters, one for each
+   media technology. The number of storage disks and capacity per disk should
+   be determined by the need of the workloads.

 Network
 ~~~~~~~
@ -238,8 +231,8 @@ Airship Installation
   section.
 * ``SITE``: Name of the site to be deployed.

-Download Airshipctl
-~~~~~~~~~~~~~~~~~~~
+Download Airship
+~~~~~~~~~~~~~~~~

 1. On the build node, install the Git package:

@ -248,25 +241,31 @@ Download Airshipctl
    sudo apt update
    sudo DEBIAN_FRONTEND=noninteractive apt -y install git

-2. Create the Airship home directory and clone the ``airshipctl`` repository:
+2. Create the Airship home directory and clone the ``airshipctl`` and ``treasuremap`` repository:

 .. code-block:: bash

    mkdir -p $AIRSHIP_CONFIG_MANIFEST_DIRECTORY
    cd $AIRSHIP_CONFIG_MANIFEST_DIRECTORY
    git clone https://opendev.org/airship/airshipctl.git
-    cd airshipctl && git checkout <release-tag|branch|commit-hash>
+    pushd airshipctl
+    git checkout <release-tag|branch|commit-hash>
+    popd
+    git clone https://opendev.org/airship/treasuremap.git
+    pushd treasuremap
+    git checkout <release-tag|branch|commit-hash>
+    popd

 Install Essential Tools
 ~~~~~~~~~~~~~~~~~~~~~~~

 1. Install the essentials tools, including kubectl, kustomize, pip, and yq.

-   From the airshipctl directory, run:
+   From the `treasuremap` directory, run:

 .. code-block:: bash

-    ./tools/deployment/10_install_essentials.sh
+    ./tools/deployment/airship-core/01_install_essentials.sh
    # Recommend to add the user to the docker group
    sudo usermod -aG docker $USER

@ -274,7 +273,7 @@ Install Essential Tools

 .. code-block:: bash

-    ./tools/deployment/21_systemwide_executable.sh
+    ./tools/deployment/airship-core/21_systemwide_executable.sh

 2. (Optional) Install Apache Web server.