From b79ef3f0d9e88fd7be2e48774658d802bf9494a2 Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Tue, 22 Feb 2022 12:56:57 +0100 Subject: [PATCH 1/4] docs: Add documentation for the cluster --- apps/emqx_conf/src/emqx_conf_schema.erl | 73 +++++++++++++++++++------ scripts/spellcheck | 2 +- 2 files changed, 57 insertions(+), 18 deletions(-) diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index aa8c64bf1..11afd497c 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/apps/emqx_conf/src/emqx_conf_schema.erl @@ -112,47 +112,58 @@ fields("cluster") -> sc(atom(), #{ mapping => "ekka.cluster_name" , default => emqxcl + , desc => "Human-friendly name of the EMQX cluster." })} , {"discovery_strategy", sc(hoconsc:enum([manual, static, mcast, dns, etcd, k8s]), #{ default => manual + , desc => "Service discovery method for the cluster nodes." })} , {"autoclean", sc(emqx_schema:duration(), #{ mapping => "ekka.cluster_autoclean" , default => "5m" + , desc => "Remove disconnected nodes from the cluster after this interval." })} , {"autoheal", sc(boolean(), #{ mapping => "ekka.cluster_autoheal" , default => true + , desc => "If true, the node will try to heal network partitions automatically." })} - , {"static", - sc(ref(cluster_static), - #{})} - , {"mcast", - sc(ref(cluster_mcast), - #{})} , {"proto_dist", sc(hoconsc:enum([inet_tcp, inet6_tcp, inet_tls]), #{ mapping => "ekka.proto_dist" , default => inet_tcp })} + , {"static", + sc(ref(cluster_static), + #{ desc => "Static service discovery mechanism, when all the nodes are known + in advance." + })} + , {"mcast", + sc(ref(cluster_mcast), + #{ desc => "Service discovery via UDP multicast." + })} , {"dns", sc(ref(cluster_dns), - #{})} + #{ desc => "Service discovery via DNS SRV records." + })} , {"etcd", sc(ref(cluster_etcd), - #{})} + #{ desc => "Service discovery using 'etcd' service." + })} , {"k8s", sc(ref(cluster_k8s), - #{})} + #{ desc => "Service discovery via Kubernetes API server." + })} ]; fields(cluster_static) -> [ {"seeds", sc(hoconsc:array(atom()), #{ default => [] + , desc => "List EMQX node names in the static cluster. See node.name." })} ]; @@ -160,34 +171,43 @@ fields(cluster_mcast) -> [ {"addr", sc(string(), #{ default => "239.192.0.1" + , desc => "Multicast IPv4 address." })} , {"ports", sc(hoconsc:array(integer()), #{ default => [4369, 4370] + , desc => "List of UDP ports used for service discovery.
+Note: probe messages are broadcasted to all the specified ports." })} , {"iface", sc(string(), #{ default => "0.0.0.0" + , desc => "IPv4 interface address." })} , {"ttl", sc(range(0, 255), #{ default => 255 + , desc => "Time-to-live (TTL) for the outgoing UDP datagrams." })} , {"loop", sc(boolean(), #{ default => true + , desc => "If true, loop UDP datagrams back to the local socket." })} , {"sndbuf", sc(emqx_schema:bytesize(), #{ default => "16KB" + , desc => "Size of the kernel-level buffer for outgoing datagrams." })} , {"recbuf", sc(emqx_schema:bytesize(), #{ default => "16KB" + , desc => "Size of the kernel-level buffer for incoming datagrams." })} , {"buffer", sc(emqx_schema:bytesize(), #{ default =>"32KB" + , desc => "Size of the user-level buffer." })} ]; @@ -195,52 +215,70 @@ fields(cluster_dns) -> [ {"name", sc(string(), #{ default => "localhost" + , desc => "The domain name of the EMQX cluster." })} , {"app", sc(string(), #{ default => "emqx" + , desc => "The symbolic name of the EMQX service." })} ]; fields(cluster_etcd) -> [ {"server", sc(emqx_schema:comma_separated_list(), - #{})} + #{ desc => "List of endpoint URLs of the etcd cluster" + })} , {"prefix", sc(string(), #{ default => "emqxcl" + , desc => "Key prefix used for EMQX service discovery." })} , {"node_ttl", sc(emqx_schema:duration(), #{ default => "1m" + , desc => "Expiration time of the etcd key associated with the node. +It is refreshed automatically, as long as the node is alive." })} , {"ssl", sc(hoconsc:ref(emqx_schema, ssl_client_opts), - #{})} + #{ desc => "Options for the TLS connection to the etcd cluster." + })} ]; fields(cluster_k8s) -> [ {"apiserver", sc(string(), - #{})} + #{ desc => "Kubernetes API endpoint URL." + })} , {"service_name", sc(string(), #{ default => "emqx" + , desc => "EMQX service name." })} , {"address_type", sc(hoconsc:enum([ip, dns, hostname]), - #{})} + #{ desc => "Address type used for connecting to the discovered nodes." + })} , {"app_name", sc(string(), #{ default => "emqx" + , desc => "This parameter should be set to the part of the node.name +before the '@'.
+For example, if the node.name is emqx@127.0.0.1, then this parameter +should be set to emqx." })} , {"namespace", sc(string(), #{ default => "default" + , desc => "Kubernetes namespace." })} , {"suffix", sc(string(), - #{default => "pod.local" + #{ default => "pod.local" + , desc => "Node name suffix.
+Note: this parameter is only relevant when address_type is dns +or hostname." })} ]; @@ -249,7 +287,7 @@ fields("node") -> sc(string(), #{ default => "emqx@127.0.0.1", desc => "Unique name of the EMQX node. It must follow %name%@FQDN or - %name%@IP format." + %name%@IPv4 format." })} , {"cookie", sc(string(), @@ -353,7 +391,8 @@ a crash dump" )} , {"cluster_call", sc(ref("cluster_call"), - #{ + #{ desc => "Options for the 'cluster call' feature that allows to execute a callback + on all nodes in the cluster." } )} ]; @@ -432,7 +471,7 @@ fields("cluster_call") -> sc(emqx_schema:duration(), #{ desc => "Time interval to clear completed but stale transactions. -Ensure that the number of completed transactions is less than the max_history." +Ensure that the number of completed transactions is less than the max_history." , default => "5m" })} ]; diff --git a/scripts/spellcheck b/scripts/spellcheck index 05dcef804..869e6637b 100755 --- a/scripts/spellcheck +++ b/scripts/spellcheck @@ -7,7 +7,7 @@ else SCHEMA="$1" fi -docker run -d --name langtool "ghcr.io/iequ1/emqx-schema-validate:0.2.0" +docker run -d --name langtool "ghcr.io/iequ1/emqx-schema-validate:0.2.1" docker exec -i langtool ./emqx_schema_validate - < "${SCHEMA}" success="$?" From a36a4943735528f9b545352e8d574a3a0e32b356 Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Tue, 22 Feb 2022 14:05:29 +0100 Subject: [PATCH 2/4] docs(cluster): Fix some definitions --- apps/emqx_conf/src/emqx_conf_schema.erl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index 11afd497c..0e759d792 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/apps/emqx_conf/src/emqx_conf_schema.erl @@ -138,8 +138,8 @@ fields("cluster") -> })} , {"static", sc(ref(cluster_static), - #{ desc => "Static service discovery mechanism, when all the nodes are known - in advance." + #{ desc => "Service discovery via static nodes. The new node joins the cluster by connecting + to one of the bootstrap nodes." })} , {"mcast", sc(ref(cluster_mcast), @@ -177,12 +177,12 @@ fields(cluster_mcast) -> sc(hoconsc:array(integer()), #{ default => [4369, 4370] , desc => "List of UDP ports used for service discovery.
-Note: probe messages are broadcasted to all the specified ports." +Note: probe messages are broadcast to all the specified ports." })} , {"iface", sc(string(), #{ default => "0.0.0.0" - , desc => "IPv4 interface address." + , desc => "Local IP address the node discovery service needs to bind to." })} , {"ttl", sc(range(0, 255), @@ -254,7 +254,7 @@ fields(cluster_k8s) -> , {"service_name", sc(string(), #{ default => "emqx" - , desc => "EMQX service name." + , desc => "EMQX broker service name." })} , {"address_type", sc(hoconsc:enum([ip, dns, hostname]), From 4116d01bfbe5ec3db67258869bc5f3422749acd4 Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Mon, 14 Mar 2022 11:19:46 +0100 Subject: [PATCH 3/4] chore(schema): Fix code style --- apps/emqx_conf/src/emqx_conf_schema.erl | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index 0e759d792..2bcbe9d38 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/apps/emqx_conf/src/emqx_conf_schema.erl @@ -129,7 +129,8 @@ fields("cluster") -> sc(boolean(), #{ mapping => "ekka.cluster_autoheal" , default => true - , desc => "If true, the node will try to heal network partitions automatically." + , desc => "If true, the node will try to heal network partitions + automatically." })} , {"proto_dist", sc(hoconsc:enum([inet_tcp, inet6_tcp, inet_tls]), @@ -138,8 +139,8 @@ fields("cluster") -> })} , {"static", sc(ref(cluster_static), - #{ desc => "Service discovery via static nodes. The new node joins the cluster by connecting - to one of the bootstrap nodes." + #{ desc => "Service discovery via static nodes. The new node joins the cluster by + connecting to one of the bootstrap nodes." })} , {"mcast", sc(ref(cluster_mcast), From 960c5ad0d5d02f762357c585bdefad513098b6ad Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Mon, 14 Mar 2022 11:05:07 +0100 Subject: [PATCH 4/4] ci: Run spellcheck --- .github/workflows/build_slim_packages.yaml | 26 ++++++++++++++++++ .github/workflows/spelling.yml | 32 ---------------------- apps/emqx_conf/src/emqx_conf_schema.erl | 6 ++-- 3 files changed, 29 insertions(+), 35 deletions(-) delete mode 100644 .github/workflows/spelling.yml diff --git a/.github/workflows/build_slim_packages.yaml b/.github/workflows/build_slim_packages.yaml index ceefb1655..0a43e46ad 100644 --- a/.github/workflows/build_slim_packages.yaml +++ b/.github/workflows/build_slim_packages.yaml @@ -84,6 +84,10 @@ jobs: with: name: ${{ matrix.profile}}-${{ matrix.otp }}-${{ matrix.os }} path: _packages/${{ matrix.profile}}/*.tar.gz + - uses: actions/upload-artifact@v2 + with: + name: "${{ matrix.profile }}_schema_dump" + path: _build/*/lib/emqx_dashboard/priv/www/static/schema.json windows: runs-on: windows-2019 @@ -204,3 +208,25 @@ jobs: with: name: macos path: _packages/**/*.tar.gz + + spellcheck: + needs: linux + strategy: + matrix: + profile: + - emqx-edge + - emqx + - emqx-enterprise + runs-on: ubuntu-20.04 + container: "ghcr.io/iequ1/emqx-schema-validate:0.2.1" + steps: + - uses: actions/download-artifact@v2 + name: Download schema dump + with: + name: "${{ matrix.profile }}_schema_dump" + path: /tmp/ + - name: Run spellcheck + run: | + cd /LanguageTool + bash start.sh > /dev/null & + ./emqx_schema_validate /tmp/${{ matrix.profile }}/lib/emqx_dashboard/priv/www/static/schema.json diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml deleted file mode 100644 index 0b9fb1b24..000000000 --- a/.github/workflows/spelling.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Spellcheck - -on: - workflow_run: - workflows: [Build slim packages] - types: - - completed - -jobs: - spellcheck_schema: - runs-on: ubuntu-latest - - strategy: - fail-fast: true - matrix: - profile: - - emqx-enterprise - otp: - - 24.2.1-1 - os: - - ubuntu20.04 - steps: - - uses: actions/checkout@v2 - - uses: dawidd6/action-download-artifact@v2 - with: - name: ${{ matrix.profile }}-${{ matrix.otp }}-${{ matrix.os }} - workflow: build_slim_packages.yaml - path: . - - name: Run spellcheck - run: | - tar zxf *.tar.gz - find . -name schema.json -exec scripts/spellcheck \{\} \; diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index 2bcbe9d38..b9157f43e 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/apps/emqx_conf/src/emqx_conf_schema.erl @@ -306,10 +306,10 @@ fields("node") -> desc => """ Path to the persistent data directory. -Possible auto-created sub-directories are: +Possible auto-created subdirectories are: - `mnesia/\`: EMQX's built-in database directory. For example, `mnesia/emqx@127.0.0.1`. - There should be only one such sub directory. + There should be only one such subdirectory. Meaning, in case the node is to be renamed (to e.g. `emqx@10.0.1.1`), the old dir should be deleted first. - `configs`: Generated configs at boot time, and cluster/local override configs. @@ -433,7 +433,7 @@ to rlog. List of core nodes that the replicant will connect to.
Note: this parameter only takes effect when the backend is set to rlog and the role is set to replicant.
-This values needs to be defined for manual or static cluster discovery mechanisms.
+This value needs to be defined for manual or static cluster discovery mechanisms.
If an automatic cluster discovery mechanism is being used (such as etcd), there is no need to set this value. """