From 0b76c12cf8dfacad90ed1be3d5a7ddd6a1cb3aa3 Mon Sep 17 00:00:00 2001 From: Luiz Aoqui Date: Wed, 8 Jul 2020 18:42:41 -0400 Subject: [PATCH] docs: fix broken links and formatting of the autoscaler docs --- website/pages/docs/autoscaling/agent.mdx | 41 ++++++++++--------- website/pages/docs/autoscaling/cli.mdx | 6 +-- website/pages/docs/autoscaling/index.mdx | 6 +-- .../pages/docs/autoscaling/plugins/index.mdx | 6 +-- .../docs/autoscaling/plugins/strategy.mdx | 4 +- .../pages/docs/autoscaling/plugins/target.mdx | 6 +-- website/pages/docs/autoscaling/policy.mdx | 14 +++---- 7 files changed, 42 insertions(+), 41 deletions(-) diff --git a/website/pages/docs/autoscaling/agent.mdx b/website/pages/docs/autoscaling/agent.mdx index 2ccdb805d..9cac049f4 100644 --- a/website/pages/docs/autoscaling/agent.mdx +++ b/website/pages/docs/autoscaling/agent.mdx @@ -32,13 +32,14 @@ the autoscaler for fetching scaling policies and scaling jobs: namespace "default" { policy = "scale" } +``` Other APM and target plugins may require additional ACLs; see the plugin documentation for more information. ## Load Order and Merging The Nomad Autoscaler agent supports multiple configuration files, which can be -provided using the [-config][autoscaler_cli_config] CLI flag. The flag can +provided using the [`-config`][autoscaler_cli_config] CLI flag. The flag can accept either a file or folder. In the case of a folder, any `.hcl` and `.json` files in the folder will be loaded and merged in lexicographical order. Directories are not loaded recursively. @@ -49,7 +50,7 @@ For example: $ nomad-autoscaler agent -config=autoscaler.conf -config=/etc/nomad-autoscaler -config=extra.json ``` -This will load configuration from autoscaler.conf, from `.hcl` and `.json` files +This will load configuration from `autoscaler.conf`, from `.hcl` and `.json` files under `/etc/nomad-autoscaler`, and finally from `extra.json`. As each file is processed, its contents are merged into the existing configuration. When merging, any non-empty values from the latest config file will append or replace @@ -62,7 +63,7 @@ The Nomad Autoscaler agent supports handling the `SIGHUP` signal for reloading w restarting the agent. When sending a `SIGHUP` signal to the agent process, the agent will perform the following actions. -- reload the contents of the scaling policy directory as defined by the [policy dir][autoscaler_cli_policy_dir] +- reload the contents of the scaling policy directory as defined by the [`-policy-dir`][autoscaler_cli_policy_dir] parameter. ## General Parameters @@ -89,10 +90,10 @@ http { ### `http` Parameters -- `bind_address` `(string "127.0.0.1")` - The HTTP address that the server will +- `bind_address` `(string: "127.0.0.1")` - The HTTP address that the server will bind to. -- `bind_port` `(int 8080)` - The port that the server will bind to. +- `bind_port` `(int: 8080)` - The port that the server will bind to. ## `nomad` Block @@ -107,36 +108,36 @@ nomad { ### `nomad` Parameters -- `address` `(string "http://127.0.0.1:4646")` - The address of the Nomad server - in the form of protocol://addr:port. +- `address` `(string: "http://127.0.0.1:4646")` - The address of the Nomad server + in the form of `protocol://addr:port`. -- `region` `(string "global")` - The region of the Nomad servers to connect with. +- `region` `(string: "global")` - The region of the Nomad servers to connect with. -- `namespace` `(string "")` - The target namespace for queries and actions bound +- `namespace` `(string: "")` - The target namespace for queries and actions bound to a namespace. -- `token` `(string "")` - The SecretID of an ACL token to use to authenticate +- `token` `(string: "")` - The SecretID of an ACL token to use to authenticate API requests with. -- `http_auth` `(string "")` - The authentication information to use when connecting +- `http_auth` `(string: "")` - The authentication information to use when connecting to a Nomad API which is using HTTP authentication. -- `ca_cert` `(string "")` - Path to a PEM encoded CA cert file to use to verify +- `ca_cert` `(string: "")` - Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. -- `ca_path` `(string "")` - Path to a directory of PEM encoded CA cert files to +- `ca_path` `(string: "")` - Path to a directory of PEM encoded CA cert files to verify the Nomad server SSL certificate. -- `client_cert` `(string "")` - Path to a PEM encoded client certificate for TLS +- `client_cert` `(string: "")` - Path to a PEM encoded client certificate for TLS authentication to the Nomad server. -- `client_key` `(string "")` - Path to an unencrypted PEM encoded private key +- `client_key` `(string: "")` - Path to an unencrypted PEM encoded private key matching the client certificate. -- `tls_server_name` `(string "")` - The server name to use as the SNI host when +- `tls_server_name` `(string: "")` - The server name to use as the SNI host when connecting via TLS. -- `skip_verify` `(bool false)` - Do not verify TLS certificates. This is strongly +- `skip_verify` `(bool: false)` - Do not verify TLS certificates. This is strongly discouraged. ## `policy` Block @@ -152,13 +153,13 @@ policy { ### `policy` Parameters -- `dir` `(string "./plugins")` - The path to a directory used to load scaling +- `dir` `(string: "./plugins")` - The path to a directory used to load scaling policies. -- `default_cooldown` `(string "5m")` - The default cooldown that will be applied +- `default_cooldown` `(string: "5m")` - The default cooldown that will be applied to all scaling policies which do not specify a cooldown period. -- `default_evaluation_interval` `(string "10s")` - The default evaluation interval +- `default_evaluation_interval` `(string: "10s")` - The default evaluation interval that will be applied to all scaling policies which do not specify an evaluation interval. diff --git a/website/pages/docs/autoscaling/cli.mdx b/website/pages/docs/autoscaling/cli.mdx index e42ade3e1..7d44bd1f4 100644 --- a/website/pages/docs/autoscaling/cli.mdx +++ b/website/pages/docs/autoscaling/cli.mdx @@ -25,10 +25,10 @@ passed in via CLI arguments. The `agent` command accepts the following arguments config files to use for configuring the Nomad Autoscaler agent. - `-log-level=`: Specify the verbosity level of Nomad Autoscaler's logs. - Valid values include DEBUG, INFO, and WARN, in decreasing order of verbosity. + Valid values include `DEBUG`, `INFO`, and `WARN`, in decreasing order of verbosity. The default is `INFO`. -- `-log-json`: Output logs in a JSON format. The default is false. +- `-log-json`: Output logs in a JSON format. The default is `false`. - `-plugin-dir=`: The plugin directory is used to discover Nomad Autoscaler plugins. If not specified, the plugin directory defaults to be that of @@ -41,7 +41,7 @@ passed in via CLI arguments. The `agent` command accepts the following arguments default is `8080`. - `-nomad-address=`: The address of the Nomad server in the form of - protocol://addr:port. The default is `http://127.0.0.1:4646`. + `protocol://addr:port`. The default is `http://127.0.0.1:4646`. - `-nomad-region=`: The region of the Nomad servers to connect with. diff --git a/website/pages/docs/autoscaling/index.mdx b/website/pages/docs/autoscaling/index.mdx index dffcbf81e..38f09a3bc 100644 --- a/website/pages/docs/autoscaling/index.mdx +++ b/website/pages/docs/autoscaling/index.mdx @@ -25,19 +25,19 @@ to have sufficient work throughput to meet service-level agreements (SLA). In Nomad, horizontal application autoscaling can be achieved by modifying the number of allocations in a task group based on the value of a relevant metric, such as CPU and memory utilization or number of open connections. This is enabled by configuring -[autoscaling policies][autoscaling_policy] on individual Nomad jobs using the [scaling block][scaling_block]. +[autoscaling policies][autoscaling_policy] on individual Nomad jobs using the [`scaling` block][scaling_block]. ## Horizontal Cluster Autoscaling Horizontal cluster autoscaling is the process of adding or removing Nomad clients from a cluster to ensure there is an appropriate amount of cluster resource for the scheduled applications. This is achieved by interacting with remote providers to start or terminate new Nomad clients based on metrics such as the remaining free schedulable CPU or memory. -Cluster scaling is enabled by configuring the [autoscaler agent][/docs/autoscaling/agent#dir] +Cluster scaling is enabled by configuring the [autoscaler agent](/docs/autoscaling/agent#dir) with policies targeting the Nomad cluster. [scaling_block]: /docs/job-specification/scaling [autoscaling_policy]: /docs/autoscaling/policy [autoscaler_github]: https://github.com/hashicorp/nomad-autoscaler [autoscaler_releases]: https://releases.hashicorp.com/nomad-autoscaler/ -[autoscaler_dockerhub]: https://hub.docker.com/repository/docker/hashicorp/nomad-autoscaler +[autoscaler_dockerhub]: https://hub.docker.com/r/hashicorp/nomad-autoscaler [autoscaler_demo]: https://github.com/hashicorp/nomad-autoscaler/tree/master/demo diff --git a/website/pages/docs/autoscaling/plugins/index.mdx b/website/pages/docs/autoscaling/plugins/index.mdx index 136eac7ec..ab37e4f83 100644 --- a/website/pages/docs/autoscaling/plugins/index.mdx +++ b/website/pages/docs/autoscaling/plugins/index.mdx @@ -16,8 +16,8 @@ flexibility of plugins allows the Nomad Autoscaler to be extended to meet specif business requirements or technology use cases. The Nomad Autoscaler currently ships with a number of built-in plugins to ease -the learning curve. Details of these can be found below, under the specific -plugin type sections. +the learning curve. Details of these can be found in the side menu, under the +specific plugin type sections. # General Options @@ -31,7 +31,7 @@ targets. with that of the agent. - `nomad_address` `(string: "")` - The address of the Nomad server in the form - of protocol://addr:port. + of `protocol://addr:port`. - `nomad_region` `(string: "")` - The region of the Nomad servers to connect with. diff --git a/website/pages/docs/autoscaling/plugins/strategy.mdx b/website/pages/docs/autoscaling/plugins/strategy.mdx index 6898eee91..ae70cb92f 100644 --- a/website/pages/docs/autoscaling/plugins/strategy.mdx +++ b/website/pages/docs/autoscaling/plugins/strategy.mdx @@ -10,8 +10,8 @@ description: Strategy plugins compare the current state of the system against th Strategy plugins compare the current state of the system against the desired state defined by the operator in the scaling policy and generate an action that will bring the system closer to the desired state. In practical terms, strategies -receive the current count and a metric value for a task group and output what -the new task group count should be. +receive the current count and a metric value for a task group or from servers in a +cluster, and output what the new count should be. ## Target Value Strategy Plugin diff --git a/website/pages/docs/autoscaling/plugins/target.mdx b/website/pages/docs/autoscaling/plugins/target.mdx index e2c249fa6..c3249ebf8 100644 --- a/website/pages/docs/autoscaling/plugins/target.mdx +++ b/website/pages/docs/autoscaling/plugins/target.mdx @@ -44,10 +44,10 @@ check { ``` - `job` `(string: "") ` - The job identifier which contains the task group to - scale as defined within the job specification [job stanza][nomad_job_stanza]. + scale as defined within the job specification [`job` stanza][nomad_job_stanza]. - `group` `(string: "")` - The name of the task group to scale as defined in the - job specification [group stanza][nomad_group_stanza]. + job specification [`group` stanza][nomad_group_stanza]. ## AWS AutoScaling Group Target @@ -147,7 +147,7 @@ check { [nomad_node_class]: https://www.nomadproject.io/docs/configuration/client#node_class [nomad_node_drain_deadline]: https://www.nomadproject.io/api-docs/nodes#deadline [nomad_scaling_stanza]: /docs/job-specification/scaling -[nomad_group_stanza]: docs/job-specification/group#group-stanza +[nomad_group_stanza]: /docs/job-specification/group#group-stanza [nomad_job_stanza]: /docs/job-specification/job#job-stanza [aws_region]: https://aws.amazon.com/about-aws/global-infrastructure/regions_az/ [aws_autoscaling]: https://aws.amazon.com/autoscaling/ diff --git a/website/pages/docs/autoscaling/policy.mdx b/website/pages/docs/autoscaling/policy.mdx index 21f852b10..53c396859 100644 --- a/website/pages/docs/autoscaling/policy.mdx +++ b/website/pages/docs/autoscaling/policy.mdx @@ -10,7 +10,7 @@ description: > # Nomad Autoscaler Scaling Policies Nomad Autoscaler scaling policies can be configured via the -[task group scaling stanza][jobspec_scaling_stanza] or by configuration +[task group `scaling` stanza][jobspec_scaling_stanza] or by configuration files stored on disk. ## Top Level Options @@ -28,17 +28,17 @@ files stored on disk. - `cooldown` - A time interval after a scaling action during which no additional scaling will be performed on the resource. It should be provided as a duration - (e.g.: "5s", "1m"). If omitted the configuration value + (e.g.: `"5s"`, `"1m"`). If omitted the configuration value [policy_default_cooldown][policy_default_cooldown_agent] from the agent will be used. - `evaluation_interval` - Defines how often the policy is evaluated by the - Autoscaler. It should be provided as a duration (e.g.: "5s", "1m"). If + Autoscaler. It should be provided as a duration (e.g.: `"5s"`, `"1m"`). If omitted the configuration value [default_evaluation_interval][eval_interval_agent] from the agent will be used. - `target` - Defines where the autoscaling target is running. Detailed information - on the configuration options can be found on the [target plugin][target_plugin_docs] + on the configuration options can be found on the [Target Plugins][target_plugin_docs] page. - `check` - Specifies one or more checks to be executed when determining if a @@ -51,17 +51,17 @@ files stored on disk. - `query` - The query to run against the specified APM. Currently this query should return a single value. Detailed information on the configuration options - can be found on the [apm plugin][apm_plugin_docs] page. + can be found on the [APM Plugins][apm_plugin_docs] page. - `strategy` - The strategy to use, and it's configuration when calculating the desired state based on the current count and the metric returned by the APM. Detailed information on the configuration options can be found on the - [strategy plugin][strategy_plugin_docs] page. + [Strategy Plugins][strategy_plugin_docs] page. ### Example A full example of a policy document that can be written into the Nomad task group -scaling stanza or via a file within the policy dir can be seen below. +`scaling` stanza or via a file within the `policy_dir` can be seen below. ```hcl min = 2