Docs for cli and target nodes

distribworks · Nov 26, 2018 · 257f202 · 257f202
1 parent 9c60fe8
commit 257f202
Show file tree

Hide file tree

Showing 8 changed files with 246 additions and 48 deletions.
diff --git a/website/content/basics/configuration.md b/website/content/basics/configuration.md
@@ -3,53 +3,15 @@ title: Configuration
 wight: 20
 ---
 
-Settings for dkron can be specified in three ways: Using a `config/dkron.json` config file, using env variables starting with `DKRON_` or using command line arguments.
+## Configuration sources
 
-## Command line options
+Settings can be specified in three ways (in order of precedence): 
 
-* `--node-name` - Name of the node, must be unique in the cluster. By default this is the hostname of the machine.
+1. Command line arguments.
+1. Environment variables starting with **`DKRON_`**
+1. **`dkron.json`** config file
 
-* `--bind-addr` - The address that dkron will bind to for communication with other dkron nodes. By default this is "0.0.0.0:8946". dkron nodes may have different ports. If a join is specified without a port, we default to locally configured port. dkron uses both TCP and UDP and use the same port for both, so if you have any firewalls be sure to allow both protocols. If this configuration value is changed and no port is specified, the default of "8946" will be used.
-
-* `--join` - Address of another agent to join upon starting up. This can be specified multiple times to specify multiple agents to join. If Dkron is unable to join with any of the specified addresses, agent startup will fail. By default, the agent won't join any nodes when it starts up.
-
-* `--advertise-addr` - The advertise flag is used to change the address that we advertise to other nodes in the cluster. By default, the bind address is advertised. However, in some cases (specifically NAT traversal), there may be a routable address that cannot be bound to. This flag enables gossiping a different address to support this. If this address is not routable, the node will be in a constant flapping state, as other nodes will treat the non-routability as a failure.
-
-* `--http-addr` - The address where the web UI will be binded. By default `:8080`
-
-* `--backend` - Backend storage to use, etcd, etcdv3, consul, zk (zookeeper) or redis. The default is etcd.
-
-* `--backend-machine` - Backend storage servers addresses to connect to. This flag can be specified multiple times. By default `127.0.0.1:2379`
-
-* `--tag` - The tag flag is used to associate a new key/value pair with the agent. The tags are gossiped and can be used to provide additional information such as roles, ports, and configuration values to other nodes. Multiple tags can be specified per agent. There is a byte size limit for the maximum number of tags, but in practice dozens of tags may be used. Tags can be changed during a config reload.
-
-* `--server` - If this agent is a dkron server, just need to be present. Absent by default.
-
-* `--keyspace` - Keyspace to use for the store. Allows to run different instances using the same storage cluster. `dkron` by default.
-
-* `--encrypt` - Key for encrypting network traffic. Must be a base64-encoded 16-byte key.
-
-* `--mail-host` - Mail server host address to use for notifications.
-
-* `--mail-port` - Mail server port.
-
-* `--mail-username` - Mail server username used for authentication.
-
-* `--mail-password` - Mail server password to use.
-
-* `--mail-from` - From email address to use.
-
-* `--webhook-url` - Webhook url to call for notifications.
-
-* `--webhook-payload` - Body of the POST request to send on webhook call.
-
-* `--webhook-header` - Headers to use when calling the webhook URL. Can be specified multiple times.
-
-* `--log-level` - Set the log level (debug, info, warn, error, fatal, panic). Defaults to "info"
-
-* `--rpc-port` - The port that Dkron will use to bind for the agent's RPC server, defaults to `6868`. The RPC address will be the bind address.
-
-# Config file example
+### Config file example
 
 ```yaml
 # Dkron example configuration file
@@ -76,3 +38,10 @@ Settings for dkron can be specified in three ways: Using a `config/dkron.json` c
 # mail-from": cron@example.com
 # mail-subject_prefix: [Dkron]
 ```
+
+### SEE ALSO
+
+* [dkron agent](/cli/dkron_agent/)	 - Start a dkron agent
+* [dkron doc](/cli/dkron_doc/)	 - Generate Markdown documentation for the Dkron CLI.
+* [dkron keygen](/cli/dkron_keygen/)	 - Generates a new encryption key
+* [dkron version](/cli/dkron_version/)	 - Show version
diff --git a/website/content/cli/_index.md b/website/content/cli/_index.md
@@ -0,0 +1,7 @@
+---
+title: "CLI"
+weight: 90
+icon: "<b>1. </b>"
+---
+
+{{% children style="h2" depth="3" description="true" %}}
diff --git a/website/content/cli/dkron.md b/website/content/cli/dkron.md
@@ -0,0 +1,31 @@
+---
+date: 2018-11-26
+title: "dkron"
+slug: dkron
+url: /cli/dkron/
+---
+## dkron
+
+Open source distributed job scheduling system
+
+### Synopsis
+
+Dkron is a system service that runs scheduled jobs at given intervals or times,
+just like the cron unix service but distributed in several machines in a cluster.
+If a machine fails (the leader), a follower will take over and keep running the scheduled jobs without human intervention.
+
+### Options
+
+```
+      --config string   config file path
+  -h, --help            help for dkron
+```
+
+### SEE ALSO
+
+* [dkron agent](/cli/dkron_agent/)	 - Start a dkron agent
+* [dkron doc](/cli/dkron_doc/)	 - Generate Markdown documentation for the Dkron CLI.
+* [dkron keygen](/cli/dkron_keygen/)	 - Generates a new encryption key
+* [dkron version](/cli/dkron_version/)	 - Show version
+
+###### Auto generated by spf13/cobra on 26-Nov-2018
diff --git a/website/content/cli/dkron_agent.md b/website/content/cli/dkron_agent.md
@@ -0,0 +1,64 @@
+---
+date: 2018-11-26
+title: "dkron agent"
+slug: dkron_agent
+url: /cli/dkron_agent/
+---
+## dkron agent
+
+Start a dkron agent
+
+### Synopsis
+
+Start a dkron agent that schedule jobs, listen for executions and run executors.
+It also runs a web UI.
+
+```
+dkron agent [flags]
+```
+
+### Options
+
+```
+      --advertise-addr string        Address used to advertise to other nodes in the cluster. By default, the bind address is advertised.
+      --advertise-rpc-port int       Use the value of rpc-port by default.
+      --backend string               store backend (default "boltdb")
+      --backend-machine strings      store backend machines addresses (default [./dkron.db])
+      --bind-addr string             Address to bind network listeners to. (default "0.0.0.0:8946")
+      --dog-statsd-addr string       DataDog Agent address.
+      --dog-statsd-tags strings      Datadog tags, specified as key:value
+      --encrypt string               Key for encrypting network traffic. Must be a base64-encoded 16-byte key.
+  -h, --help                         help for agent
+      --http-addr string             Address to bind the UI web server to. Only used when server. (default ":8080")
+      --join strings                 An initial agent to join with. This flag can be specified multiple times.
+      --keyspace string              The keyspace to use. A prefix under all data is stored for this instance. (default "dkron")
+      --log-level string             Log level (debug, info, warn, error, fatal, panic), defaults to info (default "info")
+      --mail-from string             From email address to use.
+      --mail-host string             Mail server host address to use for notifications.
+      --mail-password string         Mail server password to use.
+      --mail-payload string          Notification mail payload.
+      --mail-port string             Mail server port.
+      --mail-subject-prefix string   Notification mail subject prefix. (default "[Dkron]")
+      --mail-username string         Mail server username used for authentication.
+      --node-name string             Name of this node. Must be unique in the cluster. (default "pris.local")
+      --profile string               Profile is used to control the timing profiles used. The default if not provided is lan. (default "lan")
+      --rpc-port int                 RPC Port used to communicate with clients. Only used when server. The RPC IP Address will be the same as the bind address. (default 6868)
+      --server                       This node is running in server mode.
+      --statsd-addr string           Statsd Address.
+      --tag strings                  Tag can be specified multiple times to attach multiple key/value tag pairs to the given node. Specified as key=value
+      --webhook-header strings       Headers to use when calling the webhook URL. Can be specified multiple times.
+      --webhook-payload string       Body of the POST request to send on webhook call.
+      --webhook-url string           Webhook url to call for notifications.
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file path
+```
+
+### SEE ALSO
+
+* [dkron](/cli/dkron/)	 - Open source distributed job scheduling system
+
+###### Auto generated by spf13/cobra on 26-Nov-2018
diff --git a/website/content/cli/dkron_doc.md b/website/content/cli/dkron_doc.md
@@ -0,0 +1,40 @@
+---
+date: 2018-11-26
+title: "dkron doc"
+slug: dkron_doc
+url: /cli/dkron_doc/
+---
+## dkron doc
+
+Generate Markdown documentation for the Dkron CLI.
+
+### Synopsis
+
+Generate Markdown documentation for the Dkron CLI.
+This command is, mostly, used to create up-to-date documentation
+of Dkron's command-line interface for http://dkron.io/.
+It creates one Markdown file per command with front matter suitable
+for rendering in Hugo.
+
+```
+dkron doc [flags]
+```
+
+### Options
+
+```
+      --dir string   the directory to write the doc. (default "/tmp/dkrondoc/")
+  -h, --help         help for doc
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file path
+```
+
+### SEE ALSO
+
+* [dkron](/cli/dkron/)	 - Open source distributed job scheduling system
+
+###### Auto generated by spf13/cobra on 26-Nov-2018
diff --git a/website/content/cli/dkron_keygen.md b/website/content/cli/dkron_keygen.md
@@ -0,0 +1,37 @@
+---
+date: 2018-11-26
+title: "dkron keygen"
+slug: dkron_keygen
+url: /cli/dkron_keygen/
+---
+## dkron keygen
+
+Generates a new encryption key
+
+### Synopsis
+
+Generates a new encryption key that can be used to configure the
+  agent to encrypt traffic. The output of this command is already
+  in the proper format that the agent expects.
+
+```
+dkron keygen [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for keygen
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file path
+```
+
+### SEE ALSO
+
+* [dkron](/cli/dkron/)	 - Open source distributed job scheduling system
+
+###### Auto generated by spf13/cobra on 26-Nov-2018
diff --git a/website/content/cli/dkron_version.md b/website/content/cli/dkron_version.md
@@ -0,0 +1,35 @@
+---
+date: 2018-11-26
+title: "dkron version"
+slug: dkron_version
+url: /cli/dkron_version/
+---
+## dkron version
+
+Show version
+
+### Synopsis
+
+Show the version
+
+```
+dkron version [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for version
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file path
+```
+
+### SEE ALSO
+
+* [dkron](/cli/dkron/)	 - Open source distributed job scheduling system
+
+###### Auto generated by spf13/cobra on 26-Nov-2018
diff --git a/website/content/usage/target-nodes-spec.md b/website/content/usage/target-nodes-spec.md
@@ -15,7 +15,7 @@ The target node syntax: `[tag-value]:[count]`
 
 Target all nodes with a tag:
 
-```
+```json
 {
     "name": "job_name",
     "command": "/bin/true",
@@ -26,17 +26,32 @@ Target all nodes with a tag:
 }
 ```
 
-Target only two nodes of a group of nodes with a tag:
+{{<mermaid align="left">}}
+graph LR;
+    J("Job tags: #quot;role#quot;: #quot;web#quot;") -->|Run Job|N1["Node1 tags: #quot;role#quot;: #quot;web#quot;"]
+    J -->|Run Job|N2["Node2 tags: #quot;role#quot;: #quot;web#quot;"]
+    J -->|Run Job|N3["Node2 tags: #quot;role#quot;: #quot;web#quot;"]
+{{< /mermaid >}}
 
-```
+Target only one nodes of a group of nodes with a tag:
+
+```json
 {
     "name": "job_name",
     "command": "/bin/true",
     "schedule": "@every 2m",
     "tags": {
-        "role": "web:2"
+        "role": "web:1"
     }
 }
 ```
 
+{{<mermaid align="left">}}
+graph LR;
+    J("Job tags: #quot;role#quot;: #quot;web:1#quot;") -->|Run Job|N1["Node1 tags: #quot;role#quot;: #quot;web#quot;"]
+    J -.- N2["Node2 tags: #quot;role#quot;: #quot;web#quot;"]
+    J -.- N3["Node2 tags: #quot;role#quot;: #quot;web#quot;"]
+{{< /mermaid >}}
+
 Dkron will try to run the job in the amount of nodes indicated by that count having that tag.
+