diff --git a/requirements.txt b/requirements.txt index 81f1334a..fb2d2239 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,3 +6,4 @@ sphinx-intl==2.0.0 sphinx-sitemap==1.0.2 Jinja2==2.10.1 GitPython==2.1.11 +sphinx-tabs diff --git a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css index f9b5b040..8a68bcb7 100644 --- a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css +++ b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css @@ -169,7 +169,7 @@ th,td { margin-left: 5px; } -.active:after { +.collapsible.active:after { content: "\2212"; } diff --git a/source/conf.py b/source/conf.py index 8981a8d8..cccfdd64 100644 --- a/source/conf.py +++ b/source/conf.py @@ -34,7 +34,7 @@ import shlex #] extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx_sitemap' + 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx_sitemap', 'sphinx_tabs.tabs' ] # Add any paths that contain templates here, relative to this directory. diff --git a/source/guides/stacks/dbrs.rst b/source/guides/stacks/dbrs.rst index 43df28d4..39c318c0 100644 --- a/source/guides/stacks/dbrs.rst +++ b/source/guides/stacks/dbrs.rst @@ -254,130 +254,132 @@ Preparing PMEM for container use The cassandra-pmem image is capable of using both `fsdax` and `devdax`, the necessary steps to configure the PMEM to work with cassandra are documented here. -fsdax ------ +.. tabs:: -Verify that the PMEM is in `fsdax` mode + .. group-tab:: devdax -.. code-block:: bash + We need to verify the device we want to use is in `devdax` mode - sudo ndctl list -u + .. code-block:: bash -.. code-block:: console + sudo ndctl create-namespace -fe namespace0.0 --mode=devdax - { - "dev":"namespace0.0", - "mode":"fsdax", - "map":"mem", - "size":"4.00 GiB (4.29 GB)", - "sector_size":512, - "blockdev":"pmem0" - } + .. code-block:: console + + { + "dev":"namespace0.0", + "mode":"devdax", + "map":"dev", + "size":"3.94 GiB (4.23 GB)", + "uuid":"cb738cc7-711d-4578-bebf-1f7ba02ca169", + "daxregion":{ + "id":0, + "size":"3.94 GiB (4.23 GB)", + "align":2097152, + "devices":[ + { + "chardev":"dax0.0", + "size":"3.94 GiB (4.23 GB)" + } + ] + }, + "align":2097152 + } -If for some reason the device is not in `fsdax` mode you can reconfigure the namespace as follows: + If needed, we can reconfigure it using :command:`ndctl create-namespace -fe --mode=devdax`. -.. code-block:: bash + Before using a `devdax` device we need to clear the device: - sudo `ndctl create-namespace -fe --mode=fsdax` + .. code-block:: bash + + sudo pmempool rm -vaf /dev/dax0.0 -Once the PMEM namespace is configured, you will see a device named :file:`/dev/pmem{0-9}`. We will create a filesystem on that device. The filesystem could be `ext4` or `xfs`, for this example we are going to use `ext4`. + The `jvm.options` configuration for Apache Cassandra should look like the following: -.. code-block:: bash + .. code-block:: console - sudo mkfs.ext4 /dev/pmem0 + -Dpmem_path=/dev/dax0.0 + -Dpool_size=0 -.. code-block:: console + Where + * pmem_path is the `devdax` device. + * pool_size=0 indicates to use the entire `devdax` device. - mke2fs 1.45.2 (27-May-2019) - Creating filesystem with 1031680 4k blocks and 258048 inodes - Filesystem UUID: 303c03f5-ac4e-4462-8bf9-bc6b0fae53fe - Superblock backups stored on blocks: - 32768, 98304, 163840, 229376, 294912, 819200, 884736 + When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated. - Allocating group tables: done - Writing inode tables: done - Creating journal (16384 blocks): done - Writing superblocks and filesystem accounting information: done + .. group-tab:: fsdax + + Verify that the PMEM is in `fsdax` mode + + .. code-block:: bash + + sudo ndctl list -u + + .. code-block:: console + + { + "dev":"namespace0.0", + "mode":"fsdax", + "map":"mem", + "size":"4.00 GiB (4.29 GB)", + "sector_size":512, + "blockdev":"pmem0" + } -Once the filesystem is created, we mount it with the dax option + If for some reason the device is not in `fsdax` mode you can reconfigure the namespace as follows: -.. code-block:: bash + .. code-block:: bash - sudo mount /dev/pmem0 /mnt/pmem -o dax + sudo `ndctl create-namespace -fe --mode=fsdax` -When using `fsdax` mode cassandra-pmem creates a pool file on the pmem mountpoint, so the `jvm.options` configuration should look like the output below: + Once the PMEM namespace is configured, you will see a device named :file:`/dev/pmem{0-9}`. We will create a filesystem on that device. The filesystem could be `ext4` or `xfs`, for this example we are going to use `ext4`. -.. code-block:: console + .. code-block:: bash - -Dpmem_path=/mnt/pmem/cassandra_pool - -Dpool_size=3221225472 + sudo mkfs.ext4 /dev/pmem0 + + .. code-block:: console + + mke2fs 1.45.2 (27-May-2019) + Creating filesystem with 1031680 4k blocks and 258048 inodes + Filesystem UUID: 303c03f5-ac4e-4462-8bf9-bc6b0fae53fe + Superblock backups stored on blocks: + 32768, 98304, 163840, 229376, 294912, 819200, 884736 + + Allocating group tables: done + Writing inode tables: done + Creating journal (16384 blocks): done + Writing superblocks and filesystem accounting information: done + + + Once the filesystem is created, we mount it with the dax option + + .. code-block:: bash + + sudo mount /dev/pmem0 /mnt/pmem -o dax + + + When using `fsdax` mode cassandra-pmem creates a pool file on the pmem mountpoint, so the `jvm.options` configuration should look like the output below: + + .. code-block:: console + + -Dpmem_path=/mnt/pmem/cassandra_pool + -Dpool_size=3221225472 -Where -* `pmem_path` is the path to the pool file, which should include the path itself and the file name -* `pool_size` is the size of the pool file in bytes. If you are using the `Docker image with Apache Cassandra`_ you can pass this value as an environment variable to the container runtime in Gb and the calculation is done automatically. + Where + * `pmem_path` is the path to the pool file, which should include the path itself and the file name + * `pool_size` is the size of the pool file in bytes. If you are using the `Docker image with Apache Cassandra`_ you can pass this value as an environment variable to the container runtime in Gb and the calculation is done automatically. -Is important to note that when creating the filesystem in the pmem device certain amount of space of the device is used by the filesystem metadata so the pool_size should be smaller than the total pmem namespace size. + Is important to note that when creating the filesystem in the pmem device certain amount of space of the device is used by the filesystem metadata so the pool_size should be smaller than the total pmem namespace size. -When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated with the environment variables `CASSANDRA_PMEM_POOL_NAME` and `CASSANDRA_FSDAX_POOL_SIZE_GB`. + When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated with the environment variables `CASSANDRA_PMEM_POOL_NAME` and `CASSANDRA_FSDAX_POOL_SIZE_GB`. -devdax ------- -We need to verify the device we want to use is in `devdax` mode - -.. code-block:: bash - - sudo ndctl create-namespace -fe namespace0.0 --mode=devdax - -.. code-block:: console - - { - "dev":"namespace0.0", - "mode":"devdax", - "map":"dev", - "size":"3.94 GiB (4.23 GB)", - "uuid":"cb738cc7-711d-4578-bebf-1f7ba02ca169", - "daxregion":{ - "id":0, - "size":"3.94 GiB (4.23 GB)", - "align":2097152, - "devices":[ - { - "chardev":"dax0.0", - "size":"3.94 GiB (4.23 GB)" - } - ] - }, - "align":2097152 - } - - -If needed, we can reconfigure it using :command:`ndctl create-namespace -fe --mode=devdax`. - -Before using a `devdax` device we need to clear the device: - -.. code-block:: bash - - sudo pmempool rm -vaf /dev/dax0.0 - - -The `jvm.options` configuration for Apache Cassandra should look like the following: - -.. code-block:: console - - -Dpmem_path=/dev/dax0.0 - -Dpool_size=0 - -Where -* pmem_path is the `devdax` device. -* pool_size=0 indicates to use the entire `devdax` device. - -When using the `Docker image with Apache Cassandra`_, the file `jvm.options` is automatically populated. Run the DBRS Container @@ -385,18 +387,23 @@ Run the DBRS Container Replace `` in the following commands with the name of the image you are using. -In `devdax` mode: +.. tabs:: -.. code-block:: bash + .. group-tab:: devdax - docker run --device=/:/dev/dax0.0 --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it --name cassandra-test + In `devdax` mode: + .. code-block:: bash -In `fsdax` mode: + docker run --device=/:/dev/dax0.0 --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it --name cassandra-test -.. code-block:: bash + .. group-tab:: fsdax - docker run --mount type=bind,source=/,target=/mnt/pmem --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it -e 'CASSANDRA_FSDAX_POOL_SIZE_GB=' --name cassandra-test + In `fsdax` mode: + + .. code-block:: bash + + docker run --mount type=bind,source=/,target=/mnt/pmem --ulimit nofile=262144:262144 -p 9042:9042 -p 7000:7000 -it -e 'CASSANDRA_FSDAX_POOL_SIZE_GB=' --name cassandra-test Container Configuration