From 55ebc37af9922da0faeb2108ee63efe1c47add20 Mon Sep 17 00:00:00 2001
From: Chris Baker <1675087+cgbaker@users.noreply.github.com>
Date: Sun, 7 Mar 2021 16:21:38 +0000
Subject: [PATCH 1/3] website: documentation for autoscaler plugins

---
 .../docs/autoscaling/internals/index.mdx      |  4 ++
 .../autoscaling/internals/plugins/apm.mdx     | 48 +++++++++++++++++++
 .../autoscaling/internals/plugins/base.mdx    | 34 +++++++++++++
 .../autoscaling/internals/plugins/index.mdx   | 40 ++++++++++++++++
 .../internals/plugins/strategy.mdx            | 41 ++++++++++++++++
 .../autoscaling/internals/plugins/target.mdx  | 46 ++++++++++++++++++
 .../autoscaling/plugins/external/index.mdx    | 17 +++++++
 .../docs/autoscaling/plugins/index.mdx        | 15 +++---
 .../docs/autoscaling/plugins/target.mdx       |  2 +
 website/data/docs-navigation.js               | 23 ++++++++-
 10 files changed, 262 insertions(+), 8 deletions(-)
 create mode 100644 website/content/docs/autoscaling/internals/plugins/apm.mdx
 create mode 100644 website/content/docs/autoscaling/internals/plugins/base.mdx
 create mode 100644 website/content/docs/autoscaling/internals/plugins/index.mdx
 create mode 100644 website/content/docs/autoscaling/internals/plugins/strategy.mdx
 create mode 100644 website/content/docs/autoscaling/internals/plugins/target.mdx
 create mode 100644 website/content/docs/autoscaling/plugins/external/index.mdx

diff --git a/website/content/docs/autoscaling/internals/index.mdx b/website/content/docs/autoscaling/internals/index.mdx
index 4def6a4be..30d5c3b6e 100644
--- a/website/content/docs/autoscaling/internals/index.mdx
+++ b/website/content/docs/autoscaling/internals/index.mdx
@@ -11,3 +11,7 @@ description: >
 
 This section covers the internals of the Nomad Autoscaler and explains the
 technical details of how it functions, its architecture, and sub-systems.
+
+- [Autoscaler plugins](/docs/autoscaxling/internals/plugins)
+- [Check calculations](/docs/autoscaling/interals/checks)
+
diff --git a/website/content/docs/autoscaling/internals/plugins/apm.mdx b/website/content/docs/autoscaling/internals/plugins/apm.mdx
new file mode 100644
index 000000000..331f942ac
--- /dev/null
+++ b/website/content/docs/autoscaling/internals/plugins/apm.mdx
@@ -0,0 +1,48 @@
+---
+layout: docs
+page_title: APM Plugins
+sidebar_title: APM
+description: Learn how to author a Nomad Autoscaler APM plugin.
+---
+
+# APM Plugins
+
+APM plugins are used by the autoscaler to interact with an external APM system,
+returning metrics that are used by the autoscaler to inform scaling actions.
+
+For a real-world example of a Nomad APM plugin implementation, see the
+[Prometheus plugin](https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/apm/prometheus).
+
+## Authoring APM Plugins
+
+Authoring an APM plugin in Go can be accomplished by implementing the
+[apm.APM][apm_plugin] interface, alongside a main package to launch the plugin.
+
+The [no-op APM plugin][noop_plugin] can be used as a starting point for new APM
+plugins.
+
+## APM Plugin API
+
+The [base plugin][base_plugin] interface must be implemented in addition to the
+following functions.
+
+### `Query(query string, timeRange sdk.TimeRange) (sdk.TimestampedMetrics, error)`
+
+The `Query` function is called by the agent during policy
+evaluation. The `query` argument is the opaque string from the scaling policy,
+and the `timeRange` indicates the period of time over which the query should be
+made. The response is a series of timestamped metrics; as such, the query semantics
+should be such that the backing APM will return a time series. An example is the
+CPU utilization of a task group, averaged over all current allocations.
+
+### `QueryMultiple(query string, timeRange sdk.TimeRange) ([]sdk.TimestampedMetrics, error)`
+
+The `QueryMultiple` method is similar to `Query`, except that the interface allows
+multiple time series to be returned. This endpoint is currently only used by [DAS][das].
+An example would be to return the CPU utilization for all allocations during
+the time range.
+
+[apm_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/apm/apm.go#L11
+[base_plugin]: /docs/autoscaling/internals/plugins/base
+[noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-apm
+[das]: /docs/autoscaling#dynamic-application-sizing
diff --git a/website/content/docs/autoscaling/internals/plugins/base.mdx b/website/content/docs/autoscaling/internals/plugins/base.mdx
new file mode 100644
index 000000000..ecb5851b8
--- /dev/null
+++ b/website/content/docs/autoscaling/internals/plugins/base.mdx
@@ -0,0 +1,34 @@
+---
+layout: docs
+page_title: Base Plugin
+sidebar_title: Base
+description: Learn about how to author a Nomad Autoscaler plugin.
+---
+
+# Base Plugin
+
+The base plugin is an interface required of all autoscaler plugins,
+providing a set of common operations.
+
+## Plugin API
+
+#### `PluginInfo() (*PluginInfo, error)`
+
+A `PluginInfo` contains metadata about the plugin. For example,
+the Prometheus APM plugin returns the following;
+
+```go
+PluginInfo{
+    // Name of the plugin
+    Name: "prometheus",
+    // Plugin type: "apm", "strategy", or "target"
+    PluginType: "apm"
+}
+```
+
+#### `SetConfig(config map[string]string) error`
+
+The `SetConfig` function is called when starting an instance of the plugin. It contains the
+configuration for a named instance of the plugin as provided in the autoscaler [agent config][plugin_config].
+
+[plugin_config]: /docs/autoscaling/agent
diff --git a/website/content/docs/autoscaling/internals/plugins/index.mdx b/website/content/docs/autoscaling/internals/plugins/index.mdx
new file mode 100644
index 000000000..e367f7971
--- /dev/null
+++ b/website/content/docs/autoscaling/internals/plugins/index.mdx
@@ -0,0 +1,40 @@
+---
+layout: docs
+page_title: Plugins
+sidebar_title: Plugins
+description: Learn about how external plugins work in the Nomad Autoscaler.
+---
+
+# Plugins
+
+The Nomad Autoscaler uses a plugin framework which allows users to extend its
+functionality. The design of the plugin system is inspired by
+[plugin system][nomad_plugin_system] used in Nomad for task drivers and
+devices.
+
+The following components are currently pluggable within Nomad:
+
+- [APMs](/docs/autoscaling/internals/plugins/apm)
+- [Strategies](/docs/autoscaling/internals/plugins/strategy)
+- [Targets](/docs/autoscaling/internals/plugins/target)
+
+In addition, each plugin implements a [base](/docs/autoscaling/internals/plugins/base) plugin functionality
+
+# Architecture
+
+The Nomad Autoscaler plugin framework uses the [go-plugin][goplugin] project to expose
+a language-independent plugin interface. Plugins implement a set of gRPC
+services and methods which the Autoscaler agent manages by running the plugin
+and calling the implemented RPCs. This means that plugins are free to be
+implemented in the author's language of choice.
+
+To make plugin development easier, a set of go interfaces and structs exist for
+each plugin type that abstract the go-plugin and gRPC interfaces. The guides in
+this documentation reference these abstractions for ease of use.
+
+The existing plugins can serve as examples; in addition, no-op external plugins
+are available in the [autoscaler repo][noop_plugins].
+
+[goplugin]: https://github.com/hashicorp/go-plugin
+[nomad_plugin_system]: /docs/internals/plugins
+[noop_plugins]: https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/test
diff --git a/website/content/docs/autoscaling/internals/plugins/strategy.mdx b/website/content/docs/autoscaling/internals/plugins/strategy.mdx
new file mode 100644
index 000000000..749202bc5
--- /dev/null
+++ b/website/content/docs/autoscaling/internals/plugins/strategy.mdx
@@ -0,0 +1,41 @@
+---
+layout: docs
+page_title: Strategy Plugins
+sidebar_title: Strategy
+description: Learn how to author a Nomad Autoscaler Strategy plugin.
+---
+
+# Strategy Plugins
+
+Strategy plugins are used by the autoscaler to implement the logic of scaling strategy.
+They typically consume metrics from the configured APM plugin and the current scaling value
+from the target plugin and compute a new desired value for the scaling target.
+
+For a real-world example of a Nomad strategy plugin implementation, see the
+[`target-value` plugin][target_value].
+
+## Authoring Strategy Plugins
+
+Authoring a strategy plugin in Go can be accomplished by implementing the
+[strategy.Strategy][strategy_plugin] interface, alongside a main package to launch the plugin.
+
+The [no-op Strategy plugin][noop_plugin] can be used as a starting point for new Strategy
+plugins.
+
+## Strategy Plugin API
+
+The [base plugin][base_plugin] interface must be implemented in addition to the
+following functions.
+
+### `	Run(eval *sdk.ScalingCheckEvaluation, count int64) (*sdk.ScalingCheckEvaluation, error)`
+
+The `Run` function is called by the agent during policy
+evaluation. The `eval` argument contains [information](https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/sdk/eval_oss.go#L8)
+about the current policy evaluation, including the policy specification and the metrics from the APM. The `count`
+argument includes the current value of the scaling target. The returned struct should include the result
+from applying the strategy.
+
+[strategy_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/strategy/strategy.go#L11
+[base_plugin]: /docs/autoscaling/internals/plugins/base
+[noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-strategy
+[target_value]: https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/strategy/target-value
diff --git a/website/content/docs/autoscaling/internals/plugins/target.mdx b/website/content/docs/autoscaling/internals/plugins/target.mdx
new file mode 100644
index 000000000..614f16ee3
--- /dev/null
+++ b/website/content/docs/autoscaling/internals/plugins/target.mdx
@@ -0,0 +1,46 @@
+---
+layout: docs
+page_title: Target Plugins
+sidebar_title: Target
+description: Learn how to author a Nomad Autoscaler Target plugin.
+---
+
+# Target Plugins
+
+Target plugins are used by the autoscaler to perform a scaling action against a
+scaling target.
+
+For a real-world example of a Nomad Target plugin implementation, see the
+[Nomad group->count plugin](https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/builtin/target/nomad).
+
+## Authoring Target Plugins
+
+Authoring a target plugin in Go can be accomplished by implementing the
+[target.Target][target_plugin] interface, alongside a main package to launch the plugin.
+
+The [no-op Target plugin][noop_plugin] can be used as a starting point for new Target
+plugins.
+
+## Target Plugin API
+
+The [base plugin][base_plugin] interface must be implemented in addition to the
+following functions.
+
+### `Scale(action sdk.ScalingAction, config map[string]string) error`
+
+The `Scale` method is called by the agent during policy
+evaluation. The `action` argument specifies the details about the scaling action
+that should be made against the target (e.g., new value, metadata). Config includes
+details about the scaling target (e.g., Nomad job name, AWS autoscaling group).
+
+### `Status(config map[string]string) (*sdk.TargetStatus, error)`
+
+The `Status` method is called by the agent in order to determine the current
+status of a scaling target. This is performed as part of policy evaluation,
+and the information returned may be used by the scaling strategy to inform the
+next scaling action. Information returned includes current scaling level,
+readiness, and arbitrary metadata.
+
+[target_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/target/target.go#L12
+[base_plugin]: /docs/autoscaling/internals/plugins/base
+[noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-target
diff --git a/website/content/docs/autoscaling/plugins/external/index.mdx b/website/content/docs/autoscaling/plugins/external/index.mdx
new file mode 100644
index 000000000..21450fa2a
--- /dev/null
+++ b/website/content/docs/autoscaling/plugins/external/index.mdx
@@ -0,0 +1,17 @@
+---
+layout: docs
+page_title: 'Autoscaler Plugins: Community Supported'
+sidebar_title: Community
+description: A list of community-supported Autoscaler Plugins.
+---
+
+# Community Supported
+
+If you have authored an autoscaler plugin that you believe will be useful to the
+broader Nomad community and you are committed to maintaining the plugin, please
+file a PR to add your plugin to this page.
+
+For details on authoring an autoscaler plugin, please refer to the [plugin
+authoring guide][plugin_guide].
+
+[plugin_guide]: /docs/autoscaling/internals/plugins
diff --git a/website/content/docs/autoscaling/plugins/index.mdx b/website/content/docs/autoscaling/plugins/index.mdx
index ab37e4f83..f52321c73 100644
--- a/website/content/docs/autoscaling/plugins/index.mdx
+++ b/website/content/docs/autoscaling/plugins/index.mdx
@@ -9,15 +9,17 @@ description: Plugins are used to architect the Nomad Autoscaler into distinct ar
 
 Plugins are an essential part of the Nomad Autoscaler architecture. The Autoscaler
 uses the [go-plugin][go_plugin_github] library to implement an ecosystem of
-different types of plugins. Each plugin type is responsible for a specific task;
-APM plugins retrieve metrics about the workloads being monitored and Strategy
-plugins decide which actions Nomad should execute to keep the policy valid. The
-flexibility of plugins allows the Nomad Autoscaler to be extended to meet specific
-business requirements or technology use cases.
+different types of plugins. Each plugin type is responsible for a specific task:
+APM plugins retrieve metrics about the workloads being monitored; strategy
+plugins decide the scaling action to satisfy the scaling policy; and target
+plugins perform the scaling action. The flexibility of plugins allows the Nomad
+Autoscaler to be extended to meet specific 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 in the side menu, under the
-specific plugin type sections.
+specific plugin type sections. The autoscaler also supports external plugins; see
+this list of [community-supported plugins][community_plugins].
 
 # General Options
 
@@ -63,3 +65,4 @@ targets.
   strongly discouraged.
 
 [go_plugin_github]: https://github.com/hashicorp/go-plugin
+[community_plugins]: /docs/autoscaling/plugins/external
diff --git a/website/content/docs/autoscaling/plugins/target.mdx b/website/content/docs/autoscaling/plugins/target.mdx
index 16caf2410..3775c4bd3 100644
--- a/website/content/docs/autoscaling/plugins/target.mdx
+++ b/website/content/docs/autoscaling/plugins/target.mdx
@@ -19,6 +19,8 @@ Below is a list of plugins you can use with the Nomad Autoscaler:
 - [Azure Virtual Machine Scale Set][azure_vmss_target]
 - [Google Cloud Platform Managed Instance Groups][gcp_mig_target]
 
+
+
 ## Nomad Task Group Target
 
 The Nomad task group target indicates the scalable resource is a Nomad job
diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js
index 32987a86f..46916485f 100644
--- a/website/data/docs-navigation.js
+++ b/website/data/docs-navigation.js
@@ -419,11 +419,30 @@ export default [
       'telemetry',
       {
         category: 'plugins',
-        content: ['apm', 'strategy', 'target'],
+        content: [
+          'apm',
+          'strategy',
+          'target',
+          {
+            category: 'external',
+            content: [],
+          }
+        ],
       },
       {
         category: 'internals',
-        content: ['checks'],
+        content: [
+          'checks',
+          {
+            category: 'plugins',
+            content: [
+              'base',
+              'apm',
+              'strategy',
+              'target',
+            ],
+          }
+        ],
       },
     ],
   },

From acb116b2c46351322667ba71a1eae6c2ab1531fe Mon Sep 17 00:00:00 2001
From: Chris Baker <1675087+cgbaker@users.noreply.github.com>
Date: Mon, 22 Mar 2021 19:01:49 +0000
Subject: [PATCH 2/3] website: added senlin plugin to community plugins index

---
 .../content/docs/autoscaling/plugins/external/index.mdx    | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/website/content/docs/autoscaling/plugins/external/index.mdx b/website/content/docs/autoscaling/plugins/external/index.mdx
index 21450fa2a..a5a46fb29 100644
--- a/website/content/docs/autoscaling/plugins/external/index.mdx
+++ b/website/content/docs/autoscaling/plugins/external/index.mdx
@@ -14,4 +14,11 @@ file a PR to add your plugin to this page.
 For details on authoring an autoscaler plugin, please refer to the [plugin
 authoring guide][plugin_guide].
 
+Below is a list of community-support plugins available for the Nomad autoscaler.
+
+## Target Plugins
+
+- [OpenStack Senlin][senlin]
+
 [plugin_guide]: /docs/autoscaling/internals/plugins
+[senlin]: https://github.com/dkt26111/nomad-senlin-autoscaler

From 233dba8bc26109d5808072c302032c88a8cc27c1 Mon Sep 17 00:00:00 2001
From: Luiz Aoqui <luiz@hashicorp.com>
Date: Fri, 26 Mar 2021 16:55:24 -0400
Subject: [PATCH 3/3] docs: minor updates on autoscaling plugin guides

---
 .../docs/autoscaling/internals/index.mdx      |  3 +-
 .../autoscaling/internals/plugins/apm.mdx     | 13 ++++----
 .../autoscaling/internals/plugins/index.mdx   | 11 ++++---
 .../internals/plugins/strategy.mdx            |  8 ++---
 .../autoscaling/internals/plugins/target.mdx  | 33 +++++++++++--------
 5 files changed, 37 insertions(+), 31 deletions(-)

diff --git a/website/content/docs/autoscaling/internals/index.mdx b/website/content/docs/autoscaling/internals/index.mdx
index 30d5c3b6e..7a0b99e04 100644
--- a/website/content/docs/autoscaling/internals/index.mdx
+++ b/website/content/docs/autoscaling/internals/index.mdx
@@ -12,6 +12,5 @@ description: >
 This section covers the internals of the Nomad Autoscaler and explains the
 technical details of how it functions, its architecture, and sub-systems.
 
-- [Autoscaler plugins](/docs/autoscaxling/internals/plugins)
+- [Autoscaler plugins](/docs/autoscaling/internals/plugins)
 - [Check calculations](/docs/autoscaling/interals/checks)
-
diff --git a/website/content/docs/autoscaling/internals/plugins/apm.mdx b/website/content/docs/autoscaling/internals/plugins/apm.mdx
index 331f942ac..38ece9921 100644
--- a/website/content/docs/autoscaling/internals/plugins/apm.mdx
+++ b/website/content/docs/autoscaling/internals/plugins/apm.mdx
@@ -11,14 +11,14 @@ APM plugins are used by the autoscaler to interact with an external APM system,
 returning metrics that are used by the autoscaler to inform scaling actions.
 
 For a real-world example of a Nomad APM plugin implementation, see the
-[Prometheus plugin](https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/apm/prometheus).
+[`prometheus` plugin](https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/apm/prometheus).
 
 ## Authoring APM Plugins
 
 Authoring an APM plugin in Go can be accomplished by implementing the
-[apm.APM][apm_plugin] interface, alongside a main package to launch the plugin.
+[`apm.APM`][apm_plugin] interface, alongside a `main` package to launch the plugin.
 
-The [no-op APM plugin][noop_plugin] can be used as a starting point for new APM
+The [`no-op` APM plugin][noop_plugin] can be used as a starting point for new APM
 plugins.
 
 ## APM Plugin API
@@ -26,7 +26,7 @@ plugins.
 The [base plugin][base_plugin] interface must be implemented in addition to the
 following functions.
 
-### `Query(query string, timeRange sdk.TimeRange) (sdk.TimestampedMetrics, error)`
+#### `Query(query string, timeRange sdk.TimeRange) (sdk.TimestampedMetrics, error)`
 
 The `Query` function is called by the agent during policy
 evaluation. The `query` argument is the opaque string from the scaling policy,
@@ -35,10 +35,11 @@ made. The response is a series of timestamped metrics; as such, the query semant
 should be such that the backing APM will return a time series. An example is the
 CPU utilization of a task group, averaged over all current allocations.
 
-### `QueryMultiple(query string, timeRange sdk.TimeRange) ([]sdk.TimestampedMetrics, error)`
+#### `QueryMultiple(query string, timeRange sdk.TimeRange) ([]sdk.TimestampedMetrics, error)`
 
 The `QueryMultiple` method is similar to `Query`, except that the interface allows
-multiple time series to be returned. This endpoint is currently only used by [DAS][das].
+multiple time series to be returned. This endpoint is currently only used for
+[Dynamic Application Sizing][das].
 An example would be to return the CPU utilization for all allocations during
 the time range.
 
diff --git a/website/content/docs/autoscaling/internals/plugins/index.mdx b/website/content/docs/autoscaling/internals/plugins/index.mdx
index e367f7971..c57f4eae0 100644
--- a/website/content/docs/autoscaling/internals/plugins/index.mdx
+++ b/website/content/docs/autoscaling/internals/plugins/index.mdx
@@ -8,17 +8,18 @@ description: Learn about how external plugins work in the Nomad Autoscaler.
 # Plugins
 
 The Nomad Autoscaler uses a plugin framework which allows users to extend its
-functionality. The design of the plugin system is inspired by
+functionality. The design of the plugin system is inspired by the
 [plugin system][nomad_plugin_system] used in Nomad for task drivers and
 devices.
 
-The following components are currently pluggable within Nomad:
+The following components are currently pluggable within the Nomad Autoscaler:
 
 - [APMs](/docs/autoscaling/internals/plugins/apm)
 - [Strategies](/docs/autoscaling/internals/plugins/strategy)
 - [Targets](/docs/autoscaling/internals/plugins/target)
 
-In addition, each plugin implements a [base](/docs/autoscaling/internals/plugins/base) plugin functionality
+In addition, each plugin implements a [base](/docs/autoscaling/internals/plugins/base)
+plugin functionality.
 
 # Architecture
 
@@ -28,8 +29,8 @@ services and methods which the Autoscaler agent manages by running the plugin
 and calling the implemented RPCs. This means that plugins are free to be
 implemented in the author's language of choice.
 
-To make plugin development easier, a set of go interfaces and structs exist for
-each plugin type that abstract the go-plugin and gRPC interfaces. The guides in
+To make plugin development easier, a set of Go interfaces and structs exist for
+each plugin type that abstract the `go-plugin` and gRPC interfaces. The guides in
 this documentation reference these abstractions for ease of use.
 
 The existing plugins can serve as examples; in addition, no-op external plugins
diff --git a/website/content/docs/autoscaling/internals/plugins/strategy.mdx b/website/content/docs/autoscaling/internals/plugins/strategy.mdx
index 749202bc5..3977cf655 100644
--- a/website/content/docs/autoscaling/internals/plugins/strategy.mdx
+++ b/website/content/docs/autoscaling/internals/plugins/strategy.mdx
@@ -17,9 +17,9 @@ For a real-world example of a Nomad strategy plugin implementation, see the
 ## Authoring Strategy Plugins
 
 Authoring a strategy plugin in Go can be accomplished by implementing the
-[strategy.Strategy][strategy_plugin] interface, alongside a main package to launch the plugin.
+[`strategy.Strategy`][strategy_plugin] interface, alongside a `main` package to launch the plugin.
 
-The [no-op Strategy plugin][noop_plugin] can be used as a starting point for new Strategy
+The [`no-op` Strategy plugin][noop_plugin] can be used as a starting point for new Strategy
 plugins.
 
 ## Strategy Plugin API
@@ -27,7 +27,7 @@ plugins.
 The [base plugin][base_plugin] interface must be implemented in addition to the
 following functions.
 
-### `	Run(eval *sdk.ScalingCheckEvaluation, count int64) (*sdk.ScalingCheckEvaluation, error)`
+#### `Run(eval *sdk.ScalingCheckEvaluation, count int64) (*sdk.ScalingCheckEvaluation, error)`
 
 The `Run` function is called by the agent during policy
 evaluation. The `eval` argument contains [information](https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/sdk/eval_oss.go#L8)
@@ -38,4 +38,4 @@ from applying the strategy.
 [strategy_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/strategy/strategy.go#L11
 [base_plugin]: /docs/autoscaling/internals/plugins/base
 [noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-strategy
-[target_value]: https://github.com/hashicorp/nomad-autoscaler/tree/main/plugins/builtin/strategy/target-value
+[target_value]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/builtin/strategy/target-value
diff --git a/website/content/docs/autoscaling/internals/plugins/target.mdx b/website/content/docs/autoscaling/internals/plugins/target.mdx
index 614f16ee3..ac9a7c646 100644
--- a/website/content/docs/autoscaling/internals/plugins/target.mdx
+++ b/website/content/docs/autoscaling/internals/plugins/target.mdx
@@ -7,18 +7,19 @@ description: Learn how to author a Nomad Autoscaler Target plugin.
 
 # Target Plugins
 
-Target plugins are used by the autoscaler to perform a scaling action against a
-scaling target.
+Target plugins are used by the autoscaler to retrieve information about a
+scaling target and also to perform a scaling action against them.
 
 For a real-world example of a Nomad Target plugin implementation, see the
-[Nomad group->count plugin](https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/builtin/target/nomad).
+[Nomad `group->count` plugin][nomad_group_count_plugin].
 
 ## Authoring Target Plugins
 
 Authoring a target plugin in Go can be accomplished by implementing the
-[target.Target][target_plugin] interface, alongside a main package to launch the plugin.
+[`target.Target`][target_plugin] interface, alongside a `main` package to
+launch the plugin.
 
-The [no-op Target plugin][noop_plugin] can be used as a starting point for new Target
+The [`no-op` Target plugin][noop_plugin] can be used as a starting point for new Target
 plugins.
 
 ## Target Plugin API
@@ -26,21 +27,25 @@ plugins.
 The [base plugin][base_plugin] interface must be implemented in addition to the
 following functions.
 
-### `Scale(action sdk.ScalingAction, config map[string]string) error`
+#### `Scale(action sdk.ScalingAction, config map[string]string) error`
 
-The `Scale` method is called by the agent during policy
-evaluation. The `action` argument specifies the details about the scaling action
-that should be made against the target (e.g., new value, metadata). Config includes
-details about the scaling target (e.g., Nomad job name, AWS autoscaling group).
+The `Scale` method is called by the agent during policy evaluation. The `action`
+argument specifies the [details][scaling_action_sdk] about the scaling action
+that should be made against the target. `config` includes the details about the
+scaling target that were provided in the [scaling policy][policy_target].
 
-### `Status(config map[string]string) (*sdk.TargetStatus, error)`
+#### `Status(config map[string]string) (*sdk.TargetStatus, error)`
 
 The `Status` method is called by the agent in order to determine the current
 status of a scaling target. This is performed as part of policy evaluation,
-and the information returned may be used by the scaling strategy to inform the
-next scaling action. Information returned includes current scaling level,
-readiness, and arbitrary metadata.
+and the [information][target_status_sdk] returned may be used by the scaling
+strategy to inform the next scaling action. Information returned includes
+current scaling level, readiness, and arbitrary metadata.
 
+[nomad_group_count_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/builtin/target/nomad
 [target_plugin]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/plugins/target/target.go#L12
 [base_plugin]: /docs/autoscaling/internals/plugins/base
 [noop_plugin]: https://github.com/hashicorp/nomad-autoscaler/tree/v0.3.0/plugins/test/noop-target
+[scaling_action_sdk]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/sdk/strategy.go#L25
+[policy_target]: /docs/autoscaling/policy#target
+[target_status_sdk]: https://github.com/hashicorp/nomad-autoscaler/blob/v0.3.0/sdk/target.go#L6