From 7e3b8f6a71a9413066cd43158f4d0f861110a067 Mon Sep 17 00:00:00 2001 From: Sergei Petrosian <30409084+spetrosi@users.noreply.github.com> Date: Tue, 24 Sep 2024 10:22:06 +0200 Subject: [PATCH] ci: Add markdownlint GH workflow (#72) Add markdownlint GH workflow and config file to check all .md files --- .ansible-lint | 1 + .github/workflows/markdownlint.yml | 38 +++++ .markdownlint.yaml | 261 +++++++++++++++++++++++++++++ README.md | 1 + plugins/README.md | 4 +- roles/elasticsearch/README.md | 20 +-- roles/keyserver/README.md | 2 +- roles/mssql/README.md | 8 +- roles/pcp/README.md | 24 +-- roles/spark/README.md | 12 +- 10 files changed, 336 insertions(+), 35 deletions(-) create mode 100644 .github/workflows/markdownlint.yml create mode 100644 .markdownlint.yaml diff --git a/.ansible-lint b/.ansible-lint index ce6ab8c..6ed96d5 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -6,6 +6,7 @@ exclude_paths: - tests/roles/ - .github/ - examples/roles/ + - .markdownlint.yaml kinds: - yaml: "**/meta/collection-requirements.yml" - yaml: "**/tests/collection-requirements.yml" diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 0000000..3094acd --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,38 @@ +--- +# 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@v4 + + # CHANGELOG.md is generated automatically from PR titles and descriptions + # It might have issues but they are not critical + - name: Lint all markdown files except for CHANGELOG.md + uses: docker://avtodev/markdown-lint:master + with: + args: >- + --ignore=CHANGELOG.md + **/*.md + config: .markdownlint.yaml diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..6bf4ccd --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,261 @@ +--- +# 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/README.md b/README.md index 8d9fdc8..f3085d7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Ansible Collection - performancecopilot.metrics + ![CI Testing](https://github.com/performancecopilot/ansible-pcp/workflows/tox/badge.svg) [![Mailing List](https://img.shields.io/badge/Mailing%20List-pcp-blue.svg)](https://groups.io/g/pcp) [![Slack Team](https://img.shields.io/badge/Slack-pcp-blue.svg)](https://h7zo83mvt1.execute-api.us-west-2.amazonaws.com/Express/) diff --git a/plugins/README.md b/plugins/README.md index 6541cf7..e4b5c28 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -6,7 +6,7 @@ would contain module utils and modules respectively. Here is an example directory of the majority of plugins currently supported by Ansible: -``` +```plain └── plugins ├── action ├── become @@ -28,4 +28,4 @@ Here is an example directory of the majority of plugins currently supported by A └── vars ``` -A full list of plugin types can be found at [Working With Plugins](https://docs.ansible.com/ansible/2.9/plugins/plugins.html). \ No newline at end of file +A full list of plugin types can be found at [Working With Plugins](https://docs.ansible.com/ansible/2.9/plugins/plugins.html). diff --git a/roles/elasticsearch/README.md b/roles/elasticsearch/README.md index adc3aad..fe83a08 100644 --- a/roles/elasticsearch/README.md +++ b/roles/elasticsearch/README.md @@ -8,43 +8,43 @@ Uses features of PCP v5.2.1 and later. ## Role Variables - elasticsearch_agent: true +### elasticsearch_agent: true Collect metrics from the local Elasticsearch server. - elasticsearch_agent_port: 9200 +### elasticsearch_agent_port: 9200 Connect on given socket port for Elasticsearch metric collection. - elasticsearch_agent_authname: '' +### elasticsearch_agent_authname: '' Sets the HTTP request username for Elasticsearch metric collection. - elasticsearch_agent_password: '' +### elasticsearch_agent_password: '' Sets the HTTP request password for Elasticsearch metric collection. - elasticsearch_export_metrics: false +### elasticsearch_export_metrics: false Enable exporting of PCP metrics metadata and values to Elasticsearch. - elasticsearch_export_interval: 60 +### elasticsearch_export_interval: 60 Sets the sampling interval for exporting metric values to Elasticsearch, in seconds. - elasticsearch_export_server: 'http://localhost:9200' +### elasticsearch_export_server: `http://localhost:9200` Elasticsearch server URL for PCP metric metadata and value exporting. - elasticsearch_export_index: pcp +### elasticsearch_export_index: pcp Elasticsearch index to use for PCP metric names. - elasticsearch_export_hostid: [] +### elasticsearch_export_hostid: [] Specify the Elasticsearch host-id for measurements, default is the PCP metrics source hostname. - elasticsearch_export_type: pcp-metric +### elasticsearch_export_type: pcp-metric Specify the Elasticsearch search type for measurements. diff --git a/roles/keyserver/README.md b/roles/keyserver/README.md index 5414aff..3ef603b 100644 --- a/roles/keyserver/README.md +++ b/roles/keyserver/README.md @@ -8,7 +8,7 @@ Requires a modern version of either Valkey or Redis (preferencing the open sourc ## Role Variables - keyserver_save_to_disk: true +### keyserver_save_to_disk: true Incrementally save the database to disk. Default: true. diff --git a/roles/mssql/README.md b/roles/mssql/README.md index 4ed1a6c..a7e7e0c 100644 --- a/roles/mssql/README.md +++ b/roles/mssql/README.md @@ -10,19 +10,19 @@ The SQL Server metrics are available from PCP v5.2 and later. ## Role Variables - mssql_agent_trusted: true +### mssql_agent_trusted: true Connect to SQL Server using [Windows Authentication mode](https://docs.microsoft.com/en-us/sql/relational-databases/security/choose-an-authentication-mode?view=sql-server-ver15#connecting-through-windows-authentication) - mssql_agent_username: sa +### mssql_agent_username: sa Connect to SQL server using [SQL Server Authentication mode](https://docs.microsoft.com/en-us/sql/relational-databases/security/choose-an-authentication-mode?view=sql-server-ver15#connecting-through-sql-server-authentication). This is mutually exclusive with the mssql_agent_trusted authentication mode. - mssql_agent_password: admin +### mssql_agent_password: admin Sets the pass phrase associated with mssql_agent_username, for use when connecting with SQL Server Authentication mode (only). - mssql_agent_timeout: 2 +### mssql_agent_timeout: 2 Close the connection to SQL Server if a response is not received within this number of seconds. Subsequent requests will result in attempts to reestablish a connection. diff --git a/roles/pcp/README.md b/roles/pcp/README.md index f6ecfe7..7a4c95f 100644 --- a/roles/pcp/README.md +++ b/roles/pcp/README.md @@ -8,51 +8,51 @@ Uses features of PCP v5 and later. ## Role Variables - pcp_rest_api: true +### pcp_rest_api: true Enable the PCP REST APIs and log discovery via the [pmproxy(1)](http://man7.org/linux/man-pages/man1/pmproxy.1.html) service. Default: false. - pcp_pmlogger_interval: 60 +### pcp_pmlogger_interval: 60 Default logging interval for [pmlogger(1)](http://man7.org/linux/man-pages/man1/pmlogger.1.html) archives for logging groups that do not set an explicit sampling interval. - pcp_pmlogger_discard: 14 +### pcp_pmlogger_discard: 14 After some period, old PCP archives are discarded. This period is 14 days by default, but may be changed using this variable. Some special values are recognized for the period, namely '0' to keep no archives beyond the current one, and 'forever' or never to prevent any archives being discarded. Note that the semantics of discard are that it is measured from the time of last modification of each archive, and not from the current day. - pcp_archive_dir: /var/log/pcp/pmlogger +### pcp_archive_dir: /var/log/pcp/pmlogger Default location for [pmlogger(1)](http://man7.org/linux/man-pages/man1/pmlogger.1.html) archives, per-host directories containing daily performance metric archives will be created here when pmlogger is enabled. When [pmproxy(1)](http://man7.org/linux/man-pages/man1/pmproxy.1.html) is running with archive discovery enabled, it monitors this location. - pcp_target_hosts: [] +### pcp_target_hosts: [] An optional list of remote hostnames for which metric recording and inference rules should be installed, to be monitored from the host running the playbook. By default, all performance rules evaluating to true will be logged to the local system log (for both the local host and remote hosts in the target hosts list), and daily archives will be created below *pcp_archive_dir*/*hostname* locally, again for each host listed in the target hosts list. - pcp_pmie_endpoint: '' +### pcp_pmie_endpoint: '' Send inference events to the given webhook endpoint (URL) from [pmie(1)](http://man7.org/linux/man-pages/man1/pmie.1.html) performance rules. The default is to log these events into the local system log only. - pcp_single_control: 0 +### pcp_single_control: 0 Specifies whether the pcp_target_hosts configuration file(s) for pmie and pmlogger are in control.d form (the default) or in the single file form where /*etc*/*pcp*/*pmlogger*/*control* and /*etc*/*pcp*/*pmie*/*control* are used to setup the target hosts list for monitoring. - pcp_pmcd_localonly: 0 +### pcp_pmcd_localonly: 0 Enable remote host connections to the [pmcd(1)](http://man7.org/linux/man-pages/man1/pmcd.1.html) service. This affects most PMAPI client tools accessing live data such as including *pmlogger*, *pmchart*, *pmrep*, *pmie*, *pcp-dstat*, and so on - pcp_pmproxy_localonly: 0 +### pcp_pmproxy_localonly: 0 Enable remote host connections to the [pmproxy(1)](http://man7.org/linux/man-pages/man1/pmproxy.1.html) service. This affects client tools using the REST API such as [grafana-pcp](https://grafana-pcp.readthedocs.io/) and PMAPI client tools using the protocol proxying features of *pmproxy*. - pcp_pmlogger_localonly: 1 +### pcp_pmlogger_localonly: 1 Enable remote host connections to the [pmlogger(1)](http://man7.org/linux/man-pages/man1/pmlogger.1.html) service. This affects the optional [pmlc(1)](http://man7.org/linux/man-pages/man1/pmlc.1.html) utility. - pcp_optional_agents: [] +### pcp_optional_agents: [] Additional performance metrics domain agents (PMDAs) that should be installed, beyond the default set, to enable additional metrics. The array provided should contain shortened names for each PMDA to be enabled, such as "kvm". - pcp_optional_packages: [] +### pcp_optional_packages: [] Additional PCP packages that should be installed, beyond the default set, to enable additional metrics, export to alternate data sinks, and so on. diff --git a/roles/spark/README.md b/roles/spark/README.md index 792ad8c..2001570 100644 --- a/roles/spark/README.md +++ b/roles/spark/README.md @@ -8,27 +8,27 @@ Uses features of PCP v5.2.1 and later. ## Role Variables - spark_metrics_agent: true +### spark_metrics_agent: true Collect metrics from a Spark executor. - spark_metrics_agent_url: 'http://localhost:4040/metrics/executors/prometheus' +### spark_metrics_agent_url: `http://localhost:4040/metrics/executors/prometheus` URL for the Prometheus (OpenMetrics) endpoint in the Spark UI. This depends on the PrometheusServlet in the Spark UI, which is enabled via configuration parameter: spark.ui.prometheus.enabled=true (the default is false). This role does not configure Spark itself, only PCP, so this must be already established before this role is used. - spark_export_metrics: false +### spark_export_metrics: false Enable exporting of PCP metrics metadata and values to Spark via pcp2spark(1). - spark_export_interval: 60 +### spark_export_interval: 60 Sets the sampling interval for exporting metric values to Spark, in seconds. - spark_export_server: '127.0.0.1' +### spark_export_server: '127.0.0.1' Address on which pcp2spark(1) will listen for connections from an Apache Spark worker thread. - spark_export_port: 44325 +### spark_export_port: 44325 Specify the port for pcp2spark(1) to listen on.