From 04a6312e309894c98c5f3f4bf1b73397e66ca630 Mon Sep 17 00:00:00 2001 From: Sergei Petrosian Date: Wed, 9 Aug 2023 10:27:05 +0200 Subject: [PATCH] ci: Add markdownlint, test_html_build, and build_docs workflows - markdownlint runs against README.md to avoid any issues with converting it to HTML - test_converting_readme converts README.md > HTML and uploads this test artifact to ensure that conversion works fine - build_docs converts README.md > HTML and pushes the result to the docs branch to publish dosc to GitHub pages site. - Fix markdown issues in README.md Signed-off-by: Sergei Petrosian --- .ansible-lint | 1 + .github/workflows/ansible-test.yml | 2 + .github/workflows/build_docs.yml | 101 +++++ .github/workflows/markdownlint.yml | 34 ++ .github/workflows/test_converting_readme.yml | 43 ++ .markdownlint.yaml | 260 ++++++++++++ .pandoc_template.html5 | 166 ++++++++ CHANGELOG.md | 13 + README.md | 424 +++++++++++-------- 9 files changed, 858 insertions(+), 186 deletions(-) create mode 100644 .github/workflows/build_docs.yml create mode 100644 .github/workflows/markdownlint.yml create mode 100644 .github/workflows/test_converting_readme.yml create mode 100644 .markdownlint.yaml create mode 100644 .pandoc_template.html5 diff --git a/.ansible-lint b/.ansible-lint index 97e6105d..e99af348 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -18,6 +18,7 @@ skip_list: exclude_paths: - tests/roles/ - .github/ + - .markdownlint.yaml - examples/roles/ mock_roles: - linux-system-roles.storage diff --git a/.github/workflows/ansible-test.yml b/.github/workflows/ansible-test.yml index 6dbd5486..d38ecb85 100644 --- a/.github/workflows/ansible-test.yml +++ b/.github/workflows/ansible-test.yml @@ -38,6 +38,8 @@ jobs: - name: Convert role to collection format run: | set -euxo pipefail + # Remove to avoid running ansible-test on unrelated file + rm -f .pandoc_template.html5 TOXENV=collection lsr_ci_runtox # copy the ignore files coll_dir=".tox/ansible_collections/$LSR_ROLE2COLL_NAMESPACE/$LSR_ROLE2COLL_NAME" diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 00000000..13efaab1 --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,101 @@ +--- +# yamllint disable rule:line-length +name: Convert README.md to HTML and push to docs branch +on: # yamllint disable-line rule:truthy + push: + branches: + - main + paths: + - README.md + release: + types: + - published +permissions: + contents: read +jobs: + build_docs: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Update pip, git + run: | + set -euxo pipefail + sudo apt update + sudo apt install -y git + + - name: Check out code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Ensure the docs branch + run: | + set -euxo pipefail + branch=docs + existed_in_remote=$(git ls-remote --heads origin $branch) + + if [ -z "${existed_in_remote}" ]; then + echo "Creating $branch branch" + git config --global user.name "${{ github.actor }}" + git config --global user.email "${{ github.actor }}@users.noreply.github.com" + git checkout --orphan $branch + git reset --hard + git commit --allow-empty -m "Initializing $branch branch" + git push origin $branch + echo "Created $branch branch" + else + echo "Branch $branch already exists" + fi + + - name: Checkout the docs branch + uses: actions/checkout@v3 + with: + ref: docs + + - name: Fetch README.md and .pandoc_template.html5 template from the workflow branch + uses: actions/checkout@v3 + with: + sparse-checkout: | + README.md + .pandoc_template.html5 + sparse-checkout-cone-mode: false + path: ref_branch + - name: Set RELEASE_VERSION based on whether run on release or on push + run: | + set -euxo pipefail + if [ ${{ github.event_name }} = release ]; then + echo "RELEASE_VERSION=${{ github.event.release.tag_name }}" >> $GITHUB_ENV + elif [ ${{ github.event_name }} = push ]; then + echo "RELEASE_VERSION=latest" >> $GITHUB_ENV + else + echo Unsupported event + exit 1 + fi + + - name: Ensure that version and docs directories exist + run: mkdir -p ${{ env.RELEASE_VERSION }} docs + + - name: Convert README.md to HTML and save to the version directory + uses: docker://pandoc/core:latest + with: + args: >- + --from gfm --to html5 --toc --shift-heading-level-by=-1 + --template ref_branch/.pandoc_template.html5 + --output ${{ env.RELEASE_VERSION }}/README.html ref_branch/README.md + + - name: Copy latest README.html to docs/index.html for GitHub pages + if: env.RELEASE_VERSION == 'latest' + run: cp ${{ env.RELEASE_VERSION }}/README.html docs/index.html + + - name: Commit changes + run: | + git config --global user.name "${{ github.actor }}" + git config --global user.email "${{ github.actor }}@users.noreply.github.com" + git add ${{ env.RELEASE_VERSION }}/README.html docs/index.html + git commit -m "Update README.html for ${{ env.RELEASE_VERSION }}" + + - name: Push changes + uses: ad-m/github-push-action@master + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + branch: docs diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 00000000..98e3c4c3 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,34 @@ +--- +# yamllint disable rule:line-length +name: Markdown Lint +on: # yamllint disable-line rule:truthy + pull_request: + merge_group: + branches: + - main + types: + - checks_requested + push: + branches: + - main + workflow_dispatch: +permissions: + contents: read +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - name: Update pip, git + run: | + set -euxo pipefail + sudo apt update + sudo apt install -y git + + - name: Check out code + uses: actions/checkout@v3 + + - name: Lint README.md + uses: docker://avtodev/markdown-lint:master + with: + args: README.md + config: .markdownlint.yaml diff --git a/.github/workflows/test_converting_readme.yml b/.github/workflows/test_converting_readme.yml new file mode 100644 index 00000000..e5456137 --- /dev/null +++ b/.github/workflows/test_converting_readme.yml @@ -0,0 +1,43 @@ +--- +# yamllint disable rule:line-length +name: Test converting README.md to README.html +on: # yamllint disable-line rule:truthy + pull_request: + merge_group: + branches: + - main + types: + - checks_requested + push: + branches: + - main +permissions: + contents: read +jobs: + test_converting_readme: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Update pip, git + run: | + set -euxo pipefail + sudo apt update + sudo apt install -y git + + - name: Check out code + uses: actions/checkout@v3 + + - name: Convert README.md to HTML and save to the version directory + uses: docker://pandoc/core:latest + with: + args: >- + --from gfm --to html5 --toc --shift-heading-level-by=-1 + --template .pandoc_template.html5 + --output README.html README.md + + - name: Upload README.html as an artifact + uses: actions/upload-artifact@master + with: + name: README.html + path: README.html diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..4f8a9799 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,260 @@ +# Default state for all rules +default: true + +# Path to configuration file to extend +extends: null + +# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time +MD001: true + +# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading +MD002: + # Heading level + level: 1 + +# MD003/heading-style/header-style - Heading style +MD003: + # Heading style + style: "consistent" + +# MD004/ul-style - Unordered list style +MD004: + # List style + style: "consistent" + +# MD005/list-indent - Inconsistent indentation for list items at the same level +MD005: true + +# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line +MD006: true + +# MD007/ul-indent - Unordered list indentation +MD007: + # Spaces for indent + indent: 2 + # Whether to indent the first level of the list + start_indented: false + # Spaces for first level indent (when start_indented is set) + start_indent: 2 + +# MD009/no-trailing-spaces - Trailing spaces +MD009: + # Spaces for line break + br_spaces: 2 + # Allow spaces for empty lines in list items + list_item_empty_lines: false + # Include unnecessary breaks + strict: false + +# MD010/no-hard-tabs - Hard tabs +MD010: + # Include code blocks + code_blocks: true + # Fenced code languages to ignore + ignore_code_languages: [] + # Number of spaces for each hard tab + spaces_per_tab: 1 + +# MD011/no-reversed-links - Reversed link syntax +MD011: true + +# MD012/no-multiple-blanks - Multiple consecutive blank lines +MD012: + # Consecutive blank lines + maximum: 1 + +# Modified for LSR +# GFM does not limit line length +# MD013/line-length - Line length +MD013: false + # # Number of characters + # # line_length: 80 + # line_length: 999 + # # Number of characters for headings + # heading_line_length: 80 + # # Number of characters for code blocks + # code_block_line_length: 80 + # # Include code blocks + # code_blocks: true + # # Include tables + # tables: true + # # Include headings + # headings: true + # # Include headings + # headers: true + # # Strict length checking + # strict: false + # # Stern length checking + # stern: false + +# MD014/commands-show-output - Dollar signs used before commands without showing output +MD014: true + +# MD018/no-missing-space-atx - No space after hash on atx style heading +MD018: true + +# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading +MD019: true + +# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading +MD020: true + +# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading +MD021: true + +# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines +MD022: + # Blank lines above heading + lines_above: 1 + # Blank lines below heading + lines_below: 1 + +# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line +MD023: true + +# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content +MD024: true + +# MD025/single-title/single-h1 - Multiple top-level headings in the same document +MD025: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD026/no-trailing-punctuation - Trailing punctuation in heading +MD026: + # Punctuation characters not allowed at end of headings + punctuation: ".,;:!。，；：！" + +# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol +MD027: true + +# MD028/no-blanks-blockquote - Blank line inside blockquote +MD028: true + +# MD029/ol-prefix - Ordered list item prefix +MD029: + # List style + style: "one_or_ordered" + +# MD030/list-marker-space - Spaces after list markers +MD030: + # Spaces for single-line unordered list items + ul_single: 1 + # Spaces for single-line ordered list items + ol_single: 1 + # Spaces for multi-line unordered list items + ul_multi: 1 + # Spaces for multi-line ordered list items + ol_multi: 1 + +# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines +MD031: + # Include list items + list_items: true + +# MD032/blanks-around-lists - Lists should be surrounded by blank lines +MD032: true + +# MD033/no-inline-html - Inline HTML +MD033: + # Allowed elements + allowed_elements: [] + +# MD034/no-bare-urls - Bare URL used +MD034: true + +# MD035/hr-style - Horizontal rule style +MD035: + # Horizontal rule style + style: "consistent" + +# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading +MD036: + # Punctuation characters + punctuation: ".,;:!?。，；：！？" + +# MD037/no-space-in-emphasis - Spaces inside emphasis markers +MD037: true + +# MD038/no-space-in-code - Spaces inside code span elements +MD038: true + +# MD039/no-space-in-links - Spaces inside link text +MD039: true + +# MD040/fenced-code-language - Fenced code blocks should have a language specified +MD040: + # List of languages + allowed_languages: [] + # Require language only + language_only: false + +# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading +MD041: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD042/no-empty-links - No empty links +MD042: true + +# Modified for LSR +# Disabling, we do not need this +# MD043/required-headings/required-headers - Required heading structure +MD043: false + # # List of headings + # headings: [] + # # List of headings + # headers: [] + # # Match case of headings + # match_case: false + +# MD044/proper-names - Proper names should have the correct capitalization +MD044: + # List of proper names + names: [] + # Include code blocks + code_blocks: true + # Include HTML elements + html_elements: true + +# MD045/no-alt-text - Images should have alternate text (alt text) +MD045: true + +# MD046/code-block-style - Code block style +MD046: + # Block style + style: "consistent" + +# MD047/single-trailing-newline - Files should end with a single newline character +MD047: true + +# MD048/code-fence-style - Code fence style +MD048: + # Code fence style + style: "consistent" + +# MD049/emphasis-style - Emphasis style should be consistent +MD049: + # Emphasis style should be consistent + style: "consistent" + +# MD050/strong-style - Strong style should be consistent +MD050: + # Strong style should be consistent + style: "consistent" + +# MD051/link-fragments - Link fragments should be valid +MD051: true + +# MD052/reference-links-images - Reference links and images should use a label that is defined +MD052: true + +# MD053/link-image-reference-definitions - Link and image reference definitions should be needed +MD053: + # Ignored definitions + ignored_definitions: + - "//" diff --git a/.pandoc_template.html5 b/.pandoc_template.html5 new file mode 100644 index 00000000..f2146610 --- /dev/null +++ b/.pandoc_template.html5 @@ -0,0 +1,166 @@ +$--| GitHub HTML5 Pandoc Template" v2.2 | 2020/08/12 | pandoc v2.1.1 + + +$-------------------------------------------------------------------------> lang + + +$--============================================================================= +$-- METADATA +$--============================================================================= + + + +$-----------------------------------------------------------------------> author +$for(author-meta)$ + +$endfor$ +$-------------------------------------------------------------------------> date +$if(date-meta)$ + +$endif$ +$---------------------------------------------------------------------> keywords +$if(keywords)$ + +$endif$ +$------------------------------------------------------------------> description +$if(description)$ + +$endif$ +$------------------------------------------------------------------------> title + $if(title-prefix)$$title-prefix$ – $endif$$pagetitle$ +$--=========================================================================== +$-- CSS STYLESHEETS +$--=========================================================================== +$-- Here comes the placeholder (within double braces) that will be replaced +$-- by the CSS file in the finalized template: + +$------------------------------------------------------------------------------- + +$------------------------------------------------------------------------------- +$if(quotes)$ + +$endif$ +$-------------------------------------------------------------> highlighting-css +$if(highlighting-css)$ + +$endif$ +$--------------------------------------------------------------------------> css +$for(css)$ + +$endfor$ +$-------------------------------------------------------------------------> math +$if(math)$ + $math$ +$endif$ +$------------------------------------------------------------------------------- + +$--------------------------------------------------------------> header-includes +$for(header-includes)$ + $header-includes$ +$endfor$ +$------------------------------------------------------------------------------- + + +
+$---------------------------------------------------------------> include-before +$for(include-before)$ +$include-before$ +$endfor$ +$-->>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> IF: title +$if(title)$ +
+

$title$

+$---------------------------------------------------------------------> subtitle +$if(subtitle)$ +

$subtitle$

+$endif$ +$-----------------------------------------------------------------------> author +$for(author)$ +

$author$

+$endfor$ +$-------------------------------------------------------------------------> date +$if(date)$ +

$date$

+$endif$ +$----------------------------------------------------------------------> summary +$if(summary)$ +
+$summary$ +
+$endif$ +$------------------------------------------------------------------------------- +
+$endif$ +$--<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< END IF: title +$--------------------------------------------------------------------------> toc +$if(toc)$ +
+ +
+$endif$ +$-------------------------------------------------------------------------> body +$body$ +$----------------------------------------------------------------> include-after +$for(include-after)$ +$include-after$ +$endfor$ +$------------------------------------------------------------------------------- +
+ + diff --git a/CHANGELOG.md b/CHANGELOG.md index 370ad78e..9a2df55f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,19 @@ Changelog ========= +[1.12.2] - 2023-07-19 +-------------------- + +### Bug Fixes + +- fix: RAID volume pre cleanup (#169) +- fix: facts being gathered unnecessarily (#374) + +### Other Changes + +- ci: ansible-lint - ignore var-naming[no-role-prefix] (#371) +- ci: ansible-test ignores file for ansible-core 2.15 (#372) + [1.12.1] - 2023-07-08 -------------------- diff --git a/README.md b/README.md index a8e16759..e07dc3bf 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ This role allows users to configure local storage with minimal input. As of now, the role supports managing file systems and mount entries on + - unpartitioned disks - lvm (unpartitioned whole-disk physical volumes only) @@ -17,7 +18,7 @@ See below The role requires the `mount` module from `ansible.posix`. If you are using `ansible-core`, you must install the `ansible.posix` collection. -``` +```bash ansible-galaxy collection install -vv -r meta/collection-requirements.yml ``` @@ -34,243 +35,294 @@ parameters will inherit whatever setting the pool or volume already has. This means that to change/override role defaults in an existing pool or volume, you must explicitly specify the new values/settings in the role variables. -#### `storage_pools` +### `storage_pools` + The `storage_pools` variable is a list of pools to manage. Each pool contains a nested list of `volume` dicts as described below, as well as the following keys: -##### `name` -This specifies the name of the pool to manage/create as a string. (One -example of a pool is an LVM volume group.) +- `name` + + This specifies the name of the pool to manage/create as a string. (One + example of a pool is an LVM volume group.) + +- `type` + + This specifies the type of pool to manage. + Valid values for `type`: `lvm`. + +- `disks` + + A list which specifies the set of disks to use as backing storage for the pool. + Supported identifiers include: device node (like `/dev/sda` or `/dev/mapper/mpathb`), + device node basename (like `sda` or `mpathb`), /dev/disk/ symlink + (like `/dev/disk/by-id/wwn-0x5000c5005bc37f3f`). + + For LVM pools this can be also used to add and remove disks to/from an existing pool. + Disks in the list that are not used by the pool will be added to the pool. + Disks that are currently used by the pool but not present in the list will be removed + from the pool only if `storage_safe_mode` is set to `false`. + +- `raid_level` -##### `type` -This specifies the type of pool to manage. -Valid values for `type`: `lvm`. + When used with `type: lvm` it manages a volume group with a mdraid array of given level + on it. Input `disks` are in this case used as RAID members. + Accepted values are: `linear`, `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10` -##### `disks` -A list which specifies the set of disks to use as backing storage for the pool. -Supported identifiers include: device node (like `/dev/sda` or `/dev/mapper/mpathb`), -device node basename (like `sda` or `mpathb`), /dev/disk/ symlink -(like `/dev/disk/by-id/wwn-0x5000c5005bc37f3f`). +- `volumes` -For LVM pools this can be also used to add and remove disks to/from an existing pool. -Disks in the list that are not used by the pool will be added to the pool. -Disks that are currently used by the pool but not present in the list will be removed -from the pool only if `storage_safe_mode` is set to `false`. + This is a list of volumes that belong to the current pool. It follows the + same pattern as the `storage_volumes` variable, explained below. -##### `raid_level` -When used with `type: lvm` it manages a volume group with a mdraid array of given level -on it. Input `disks` are in this case used as RAID members. -Accepted values are: `linear`, `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10` +- `encryption` -##### `volumes` -This is a list of volumes that belong to the current pool. It follows the -same pattern as the `storage_volumes` variable, explained below. + This specifies whether the pool will be encrypted using LUKS. + __WARNING__: Toggling encryption for a pool is a destructive operation, meaning + the pool itself will be removed as part of the process of + adding/removing the encryption layer. -##### `encryption` -This specifies whether the pool will be encrypted using LUKS. -__WARNING__: Toggling encryption for a pool is a destructive operation, meaning - the pool itself will be removed as part of the process of - adding/removing the encryption layer. +- `encryption_password` -##### `encryption_password` -This string specifies a password or passphrase used to unlock/open the LUKS volume(s). + This string specifies a password or passphrase used to unlock/open the LUKS volume(s). -##### `encryption_key` -This string specifies the full path to the key file on the managed nodes used to unlock -the LUKS volume(s). It is the responsibility of the user of this role to securely copy -this file to the managed nodes, or otherwise ensure that the file is on the managed -nodes. +- `encryption_key` -##### `encryption_cipher` -This string specifies a non-default cipher to be used by LUKS. + This string specifies the full path to the key file on the managed nodes used to unlock + the LUKS volume(s). It is the responsibility of the user of this role to securely copy + this file to the managed nodes, or otherwise ensure that the file is on the managed + nodes. -##### `encryption_key_size` -This integer specifies the LUKS key size (in bytes). +- `encryption_cipher` -##### `encryption_luks_version` -This integer specifies the LUKS version to use. + ifies a non-default cipher to be used by LUKS. +- `encryption_key_size` + + s the LUKS key size (in bytes). + +- `encryption_luks_version` + + This integer specifies the LUKS version to use. + +### `storage_volumes` -#### `storage_volumes` The `storage_volumes` variable is a list of volumes to manage. Each volume has the following variables: -##### `name` -This specifies the name of the volume. +- `name` -##### `type` -This specifies the type of volume on which the file system will reside. -Valid values for `type`: `lvm`, `disk` or `raid`. -The default is determined according to the OS and release (currently `lvm`). + This specifies the name of the volume. -##### `disks` -This specifies the set of disks to use as backing storage for the file system. -This is currently only relevant for volumes of type `disk`, where the list -must contain only a single item. +- `type` -##### `size` -The `size` specifies the size of the file system. The format for this is intended to -be human-readable, e.g.: "10g", "50 GiB". The size of LVM volumes can be specified as a -percentage of the pool/VG size, eg: "50%" as of v1.4.2. + This specifies the type of volume on which the file system will reside. + Valid values for `type`: `lvm`, `disk` or `raid`. + The default is determined according to the OS and release (currently `lvm`). -When using `compression` or `deduplication`, `size` can be set higher than actual available space, -e.g.: 3 times the size of the volume, based on duplicity and/or compressibility of stored data. +- `disks` -__NOTE__: The requested volume size may be reduced as necessary so the volume can - fit in the available pool space, but only if the required reduction is - not more than 2% of the requested volume size. - -##### `fs_type` -This indicates the desired file system type to use, e.g.: "xfs", "ext4", "swap". -The default is determined according to the OS and release -(currently `xfs` for all the supported systems). - -##### `fs_label` -The `fs_label` is a string to be used for a file system label. - -##### `fs_create_options` -The `fs_create_options` specifies custom arguments to `mkfs` as a string. - -##### `mount_point` -The `mount_point` specifies the directory on which the file system will be mounted. - -##### `mount_options` -The `mount_options` specifies custom mount options as a string, e.g.: 'ro'. - -##### `mount_user` -The `mount_user` specifies desired owner of the mount directory. - -##### `mount_group` -The `mount_group` specifies desired group of the mount directory. - -##### `mount_mode` -The `mount_mode` specifies desired permissions of the mount directory. - -##### `raid_level` -Specifies RAID level. LVM RAID can be created as well. -"Regular" RAID volume requires type to be `raid`. -LVM RAID needs that volume has `storage_pools` parent with type `lvm`, -`raid_disks` need to be specified as well. -Accepted values are: -* for LVM RAID volume: `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10`, `striped`, `mirror` -* for RAID volume: `linear`, `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10` - -__WARNING__: Changing `raid_level` for a volume is a destructive operation, meaning - all data on that volume will be lost as part of the process of - removing old and adding new RAID. RAID reshaping is currently not - supported. - -##### `raid_device_count` -When type is `raid` specifies number of active RAID devices. - -##### `raid_spare_count` -When type is `raid` specifies number of spare RAID devices. - -##### `raid_metadata_version` -When type is `raid` specifies RAID metadata version as a string, e.g.: '1.0'. - -##### `raid_chunk_size` -When type is `raid` specifies RAID chunk size as a string, e.g.: '512 KiB'. -Chunk size has to be multiple of 4 KiB. - -##### `raid_stripe_size` -When type is `lvm` specifies LVM RAID stripe size as a string, e.g.: '512 KiB'. - -##### `raid_disks` -Specifies which disks should be used for LVM RAID volume. -`raid_level` needs to be specified and volume has to have `storage_pools` parent with type `lvm`. -Accepts sublist of `disks` of parent `storage_pools`. -In case multiple LVM RAID volumes within the same storage pool, the same disk can be used -in multiple `raid_disks`. - -##### `encryption` -This specifies whether the volume will be encrypted using LUKS. -__WARNING__: Toggling encryption for a volume is a destructive operation, meaning - all data on that volume will be removed as part of the process of - adding/removing the encryption layer. - -##### `encryption_password` -This string specifies a password or passphrase used to unlock/open the LUKS volume. - -##### `encryption_key` -This string specifies the full path to the key file on the managed nodes used to unlock -the LUKS volume(s). It is the responsibility of the user of this role to securely copy -this file to the managed nodes, or otherwise ensure that the file is on the managed -nodes. - -##### `encryption_cipher` -This string specifies a non-default cipher to be used by LUKS. - -##### `encryption_key_size` -This integer specifies the LUKS key size (in bits). - -##### `encryption_luks_version` -This integer specifies the LUKS version to use. - -##### `deduplication` -This specifies whether the Virtual Data Optimizer (VDO) will be used. -When set, duplicate data stored on storage volume will be -deduplicated resulting in more storage capacity. -Can be used together with `compression` and `vdo_pool_size`. -Volume has to be part of the LVM `storage_pool`. -Limit one VDO `storage_volume` per `storage_pool`. -Underlying volume has to be at least 9 GB (bare minimum is around 5 GiB). - -##### `compression` -This specifies whether the Virtual Data Optimizer (VDO) will be used. -When set, data stored on storage volume will be -compressed resulting in more storage capacity. -Volume has to be part of the LVM `storage_pool`. -Can be used together with `deduplication` and `vdo_pool_size`. -Limit one VDO `storage_volume` per `storage_pool`. - -##### `vdo_pool_size` -When Virtual Data Optimizer (VDO) is used, this specifies the actual size the volume -will take on the device. Virtual size of VDO volume is set by `size` parameter. -`vdo_pool_size` format is intended to be human-readable, -e.g.: "30g", "50GiB". -Default value is equal to the size of the volume. + This specifies the set of disks to use as backing storage for the file system. + This is currently only relevant for volumes of type `disk`, where the list + must contain only a single item. + +- `size` + + The `size` specifies the size of the file system. The format for this is intended to + be human-readable, e.g.: "10g", "50 GiB". The size of LVM volumes can be specified as a + percentage of the pool/VG size, eg: "50%" as of v1.4.2. + + When using `compression` or `deduplication`, `size` can be set higher than actual available space, + e.g.: 3 times the size of the volume, based on duplicity and/or compressibility of stored data. + + __NOTE__: The requested volume size may be reduced as necessary so the volume can + fit in the available pool space, but only if the required reduction is + not more than 2% of the requested volume size. + +- `fs_type` + + This indicates the desired file system type to use, e.g.: "xfs", "ext4", "swap". + The default is determined according to the OS and release + (currently `xfs` for all the supported systems). + +- `fs_label` + + The `fs_label` is a string to be used for a file system label. + +- `fs_create_options` + + The `fs_create_options` specifies custom arguments to `mkfs` as a string. + +- `mount_point` + + The `mount_point` specifies the directory on which the file system will be mounted. + +- `mount_options` + + The `mount_options` specifies custom mount options as a string, e.g.: 'ro'. + +- `mount_user` + + The `mount_user` specifies desired owner of the mount directory. + +- `mount_group` + + The `mount_group` specifies desired group of the mount directory. + +- `mount_mode` + + The `mount_mode` specifies desired permissions of the mount directory. + +- `raid_level` + + Specifies RAID level. LVM RAID can be created as well. + "Regular" RAID volume requires type to be `raid`. + LVM RAID needs that volume has `storage_pools` parent with type `lvm`, + `raid_disks` need to be specified as well. + Accepted values are: + + - for LVM RAID volume: `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10`, `striped`, `mirror` + - for RAID volume: `linear`, `raid0`, `raid1`, `raid4`, `raid5`, `raid6`, `raid10` + + __WARNING__: Changing `raid_level` for a volume is a destructive operation, meaning + all data on that volume will be lost as part of the process of + removing old and adding new RAID. RAID reshaping is currently not + supported. + +- `raid_device_count` + + When type is `raid` specifies number of active RAID devices. + +- `raid_spare_count` + + When type is `raid` specifies number of spare RAID devices. + +- `raid_metadata_version` + + When type is `raid` specifies RAID metadata version as a string, e.g.: '1.0'. + +- `raid_chunk_size` + + When type is `raid` specifies RAID chunk size as a string, e.g.: '512 KiB'. + Chunk size has to be multiple of 4 KiB. + +- `raid_stripe_size` + + When type is `lvm` specifies LVM RAID stripe size as a string, e.g.: '512 KiB'. + +- `raid_disks` + + Specifies which disks should be used for LVM RAID volume. + `raid_level` needs to be specified and volume has to have `storage_pools` parent with type `lvm`. + Accepts sublist of `disks` of parent `storage_pools`. + In case multiple LVM RAID volumes within the same storage pool, the same disk can be used + in multiple `raid_disks`. + +- `encryption` + + This specifies whether the volume will be encrypted using LUKS. + __WARNING__: Toggling encryption for a volume is a destructive operation, meaning + all data on that volume will be removed as part of the process of + adding/removing the encryption layer. + +- `encryption_password` + + This string specifies a password or passphrase used to unlock/open the LUKS volume. + +- `encryption_key` + + This string specifies the full path to the key file on the managed nodes used to unlock + the LUKS volume(s). It is the responsibility of the user of this role to securely copy + this file to the managed nodes, or otherwise ensure that the file is on the managed + nodes. + +- `encryption_cipher` + + This string specifies a non-default cipher to be used by LUKS. + +- `encryption_key_size` + + This integer specifies the LUKS key size (in bits). + +- `encryption_luks_version` + + This integer specifies the LUKS version to use. + +- `deduplication` + + This specifies whether the Virtual Data Optimizer (VDO) will be used. + When set, duplicate data stored on storage volume will be + deduplicated resulting in more storage capacity. + Can be used together with `compression` and `vdo_pool_size`. + Volume has to be part of the LVM `storage_pool`. + Limit one VDO `storage_volume` per `storage_pool`. + Underlying volume has to be at least 9 GB (bare minimum is around 5 GiB). + +- `compression` + + This specifies whether the Virtual Data Optimizer (VDO) will be used. + When set, data stored on storage volume will be + compressed resulting in more storage capacity. + Volume has to be part of the LVM `storage_pool`. + Can be used together with `deduplication` and `vdo_pool_size`. + Limit one VDO `storage_volume` per `storage_pool`. + +- `vdo_pool_size` + + When Virtual Data Optimizer (VDO) is used, this specifies the actual size the volume + will take on the device. Virtual size of VDO volume is set by `size` parameter. + `vdo_pool_size` format is intended to be human-readable, + e.g.: "30g", "50GiB". + Default value is equal to the size of the volume. + +### `cached` -#### `cached` This specifies whether the volume should be cached or not. This is currently supported only for LVM volumes where dm-cache is used. -#### `cache_size` +### `cache_size` + Size of the cache. `cache_size` format is intended to be human-readable, e.g.: "30g", "50GiB". -#### `cache_mode` +### `cache_mode` + Mode for the cache. Supported values include `writethrough` (default) and `writeback`. -#### `cache_devices` +### `cache_devices` + List of devices that will be used for the cache. These should be either physical volumes or drives these physical volumes are allocated on. Generally you want to select fast devices like SSD or NVMe drives for cache. -#### `thin` +### `thin` + Whether the volume should be thinly provisioned or not. This is supported only for LVM volumes. -#### `thin_pool_name` +### `thin_pool_name` + For `thin` volumes, this can be used to specify the name of the LVM thin pool that will be used for the volume. If the pool with the provided name already exists, the volume will be added to that pool. If it doesn't exist a new pool named `thin_pool_name` will be created. If not specified: -* if there are no existing thin pools present, a new thin pool will be created with an automatically - generated name, -* if there is exactly one existing thin pool, the thin volume will be added to it and -* if there are multiple thin pools present an exception will be raised. -#### `thin_pool_size` +- if there are no existing thin pools present, a new thin pool will be created with an automatically + generated name, +- if there is exactly one existing thin pool, the thin volume will be added to it and +- if there are multiple thin pools present an exception will be raised. + +### `thin_pool_size` + Size for the thin pool. `thin_pool_size` format is intended to be human-readable, e.g.: "30g", "50GiB". -#### `storage_safe_mode` +### `storage_safe_mode` + When true (the default), an error will occur instead of automatically removing existing devices and/or formatting. -#### `storage_udevadm_trigger` +### `storage_udevadm_trigger` + When true (the default is false), the role will use udevadm trigger to cause udev changes to take effect immediately. This may help on some platforms with "buggy" udev.