diff --git a/website/pages/docs/autoscaling/plugins/target.mdx b/website/pages/docs/autoscaling/plugins/target.mdx index 25d13917c..9cb4b4de8 100644 --- a/website/pages/docs/autoscaling/plugins/target.mdx +++ b/website/pages/docs/autoscaling/plugins/target.mdx @@ -11,6 +11,12 @@ Target Plugins determine where the resource to be autoscaled is located. All target plugins support the `dry-run` policy config parameter which allows a policy to be evaluated, but will noop any suggested changes. +Below is a list of plugins you can use with the Nomad Autoscaler: +- [Nomad Task Group][nomad_task_group_target] +- [Dynamic Application Sizing Nomad Task][das_task_target] +- [AWS AutoScaling Group][aws_asg_target] +- [Azure Virtual Machine Scale Set][azure_vmss_target] + ## Nomad Task Group Target The Nomad task group target indicates the scalable resource is a Nomad job @@ -214,6 +220,118 @@ check "hashistack-allocated-cpu" { - `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad clients should be [purged][nomad_node_purge] when performing scale in actions. +## Azure Virtual Machine Scale Set Target + +The Azure VMSS target plugin allows for the scaling of the Nomad cluster clients +via manipulating [Azure Virtual Machine Scale Sets][azure_virtual_machine_scale_sets]. + +~> The Azure VMSS target plugin requires Azure fingerprinting, which became +available in Nomad 1.0. If you are running a previous version of Nomad you will +to set a [meta tag][client_meta_tag] in all of your nodes. + +### Agent Configuration Options + +To use the Azure VMSS target plugin, the agent configuration needs to be populated +with the appropriate target block. Authentication to the Azure API can be supplied +in a number of ways. + + +#### Virtual Machine Identities + +When using [virtual machine identities][vm_identity] you will need to provide a +user-managed identity with the `Contributor` role and set the `subscription_id` +in the Autoscaler configuration file: + +```hcl +target "azure-vmss" { + driver = "azure-vmss" + config = { + subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" + } +} +``` + +#### Configuration file + +Credentials should be injected into the configuration via a template rather +than as environment variables. This ensures the credentials are passed only to +the plugin, rather than being available for all plugins and the agent process. +It is recommended, if possible to use the +[Vault Azure Secrets engine][vault_azure_backend] for supplying access +credentials to the plugin. + +```hcl +target "azure-vmss" { + driver = "azure-vmss" + config = { + tenant_id = "02e99e69-91b0-4d0a-bd61-bf5c08fbfbab" + client_id = "34c276fa-2a74-4cf9-9fce-4e60642274cb" + secret_access_key = "ThisIrznTIS_~FAKEj4X93FTyAgilUC511" + subscription_id = "ee0886ab-5cc2-4583-a3f0-c4bfd044ee82" + } +} +``` + +- `tenant_id` `(string: "")` - The ID of the tenant to authenticate to. + +- `client_id` `(string: "")` - The app ID of the user-assigned identity in Azure + Active Directory. + +- `secret_access_key` `(string: "")` - The secret key ID used to authenticate + with the Azure API. + +- `subscription_id` `(string: "")` - The ID of the subscription to authenticate + to. + +#### Nomad ACL + +When using a Nomad cluster with ACLs enabled, the plugin will require an ACL token +which provides the following permissions: + +```hcl +node { + policy = "write" +} +``` + +### Policy Configuration Options + +```hcl +check "clients-azure-vmss" { + ... + target "azure-vmss" { + resource_group = "prod" + vm_scale_set = "hashistack-client-set" + node_class = "hashistack" + node_drain_deadline = "5m" + node_purge = "true" + } + ... +``` + +- `resource_group` `(string: )` - The name of the [Azure resource group][azure_resource_group] + within which the virtual machine scale set resides. + +- `vm_scale_set` `(string: )` - The name of the Azure virtual machine + scale set to interact with when performing scaling actions. + +- `node_class` `(string: )` - The Nomad [client node class][nomad_node_class] + identifier used to group nodes into a pool of resource. + +- `node_drain_deadline` `(duration: "15m")` The Nomad [drain deadline][nomad_node_drain_deadline] + to use when performing node draining actions. + +- `node_purge` `(bool: "false")` A boolean flag to determine whether Nomad clients should + be [purged][nomad_node_purge] when performing scale in actions. + +### Client meta tag + +The Azure VMSS target plugin requires Nomad 1.0 for Azure fingerprinting. +Alternatively, you can set a [client meta tag][client_meta_tag_docs] called +`unique.platform.azure.name` with the value being the Azure VMSS node name. +This can be retrieved programatically via the +[Azure Instance Metadata service][azure_instance_metadata]. + [nomad_node_class]: /docs/configuration/client#node_class [nomad_node_drain_deadline]: /api-docs/nodes#deadline [nomad_scaling_stanza]: /docs/job-specification/scaling @@ -229,3 +347,14 @@ check "hashistack-allocated-cpu" { [nomad_namespace_parameter]: /docs/job-specification/job#namespace [nomad_region_parameter]: /docs/job-specification/job#region [nomad_autoscaler_policy]: /docs/autoscaling/policy +[azure_virtual_machine_scale_sets]: https://docs.microsoft.com/en-us/azure/virtual-machine-scale-sets/overview +[vault_azure_backend]: https://www.vaultproject.io/docs/secrets/azure +[azure_resource_group]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group +[nomad_task_group_target]: /docs/autoscaling/plugins/target#nomad-task-group-target +[aws_asg_target]: /docs/autoscaling/plugins/target#aws-autoscaling-group-target +[azure_vmss_target]: /docs/autoscaling/plugins/target#azure-virtual-machine-scale-set-target +[vm_identity]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/ +[client_meta_tag_docs]: https://www.nomadproject.io/docs/configuration/client#meta +[client_meta_tag]: /docs/autoscaling/plugins/target#client-meta-tag +[azure_instance_metadata]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service +[das_task_target]: /docs/autoscaling/plugins/target#dynamic-application-sizing-nomad-task-target