Registers a target with a maintenance window.
See also: AWS API Documentation
register-target-with-maintenance-window
--window-id <value>
--resource-type <value>
--targets <value>
[--owner-information <value>]
[--name <value>]
[--description <value>]
[--client-token <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
--window-id
(string)
The ID of the maintenance window the target should be registered with.
--resource-type
(string)
The type of target being registered with the maintenance window.
Possible values:
INSTANCE
RESOURCE_GROUP
--targets
(list)
The targets to register with the maintenance window. In other words, the managed nodes to run commands on when the maintenance window runs.
Note
If a single maintenance window task is registered with multiple targets, its task invocations occur sequentially and not in parallel. If your task must run on multiple targets at the same time, register a task for each target individually and assign each task the same priority level.
You can specify targets using managed node IDs, resource group names, or tags that have been applied to managed nodes.
Example 1 : Specify managed node IDs
Key=InstanceIds,Values=<instance-id-1>,<instance-id-2>,<instance-id-3>
Example 2 : Use tag key-pairs applied to managed nodes
Key=tag:<my-tag-key>,Values=<my-tag-value-1>,<my-tag-value-2>
Example 3 : Use tag-keys applied to managed nodes
Key=tag-key,Values=<my-tag-key-1>,<my-tag-key-2>
Example 4 : Use resource group names
Key=resource-groups:Name,Values=<resource-group-name>
Example 5 : Use filters for resource group types
Key=resource-groups:ResourceTypeFilters,Values=<resource-type-1>,<resource-type-2>
Note
For
Key=resource-groups:ResourceTypeFilters
, specify resource types in the following format
Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC
For more information about these examples formats, including the best use case for each one, see Examples: Register targets with a maintenance window in the Amazon Web Services Systems Manager User Guide .
(structure)
An array of search criteria that targets managed nodes using a key-value pair that you specify.
Note
One or more targets must be specified for maintenance window Run Command-type tasks. Depending on the task, targets are optional for other maintenance window task types (Automation, Lambda, and Step Functions). For more information about running tasks that don’t specify targets, see Registering maintenance window tasks without targets in the Amazon Web Services Systems Manager User Guide .
Supported formats include the following.
Key=InstanceIds,Values=<instance-id-1>,<instance-id-2>,<instance-id-3>
Key=tag:<my-tag-key>,Values=<my-tag-value-1>,<my-tag-value-2>
Key=tag-key,Values=<my-tag-key-1>,<my-tag-key-2>
Run Command and Maintenance window targets only :
Key=resource-groups:Name,Values=<resource-group-name>
Maintenance window targets only :
Key=resource-groups:ResourceTypeFilters,Values=<resource-type-1>,<resource-type-2>
Automation targets only :
Key=ResourceGroup;Values=<resource-group-name>
For example:
Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
Key=tag:CostCenter,Values=CostCenter1,CostCenter2,CostCenter3
Key=tag-key,Values=Name,Instance-Type,CostCenter
Run Command and Maintenance window targets only :
Key=resource-groups:Name,Values=ProductionResourceGroup
This example demonstrates how to target all resources in the resource group ProductionResourceGroup in your maintenance window.Maintenance window targets only :
Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::INSTANCE,AWS::EC2::VPC
This example demonstrates how to target only Amazon Elastic Compute Cloud (Amazon EC2) instances and VPCs in your maintenance window.Automation targets only :
Key=ResourceGroup,Values=MyResourceGroup
State Manager association targets only :
Key=InstanceIds,Values=*
This example demonstrates how to target all managed instances in the Amazon Web Services Region where the association was created.For more information about how to send commands that target managed nodes using
Key,Value
parameters, see Targeting multiple instances in the Amazon Web Services Systems Manager User Guide .Key -> (string)
User-defined criteria for sending commands that target managed nodes that meet the criteria.
Values -> (list)
User-defined criteria that maps to
Key
. For example, if you specifiedtag:ServerRole
, you could specifyvalue:WebServer
to run a command on instances that include EC2 tags ofServerRole,WebServer
.Depending on the type of target, the maximum number of values for a key might be lower than the global maximum of 50.
(string)
Shorthand Syntax:
Key=string,Values=string,string ...JSON Syntax:
[ { "Key": "string", "Values": ["string", ...] } ... ]
--owner-information
(string)User-provided value that will be included in any Amazon CloudWatch Events events raised while running tasks for these targets in this maintenance window.
--name
(string)An optional name for the target.
--description
(string)An optional description for the target.
--client-token
(string)User-provided idempotency token.
--cli-input-json
|--cli-input-yaml
(string) Reads arguments from the JSON string provided. The JSON string follows the format provided by--generate-cli-skeleton
. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with--cli-input-yaml
.
--generate-cli-skeleton
(string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the valueinput
, prints a sample input JSON that can be used as an argument for--cli-input-json
. Similarly, if providedyaml-input
it will print a sample input YAML that can be used with--cli-input-yaml
. If provided with the valueoutput
, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.Global Options¶
--debug
(boolean)Turn on debug logging.
--endpoint-url
(string)Override command’s default URL with the given URL.
--no-verify-ssl
(boolean)By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.
--no-paginate
(boolean)Disable automatic pagination.
--output
(string)The formatting style for command output.
json
text
table
yaml
yaml-stream
--query
(string)A JMESPath query to use in filtering the response data.
--profile
(string)Use a specific profile from your credential file.
--region
(string)The region to use. Overrides config/env settings.
--version
(string)Display the version of this tool.
--color
(string)Turn on/off color output.
on
off
auto
--no-sign-request
(boolean)Do not sign requests. Credentials will not be loaded if this argument is provided.
--ca-bundle
(string)The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.
--cli-read-timeout
(int)The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.
--cli-connect-timeout
(int)The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.
--cli-binary-format
(string)The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob
fileb://
will always be treated as binary and use the file contents directly regardless of thecli-binary-format
setting. When usingfile://
the file contents will need to properly formatted for the configuredcli-binary-format
.
base64
raw-in-base64-out
--no-cli-pager
(boolean)Disable cli pager for output.
--cli-auto-prompt
(boolean)Automatically prompt for CLI input parameters.
--no-cli-auto-prompt
(boolean)Disable automatically prompt for CLI input parameters.
Examples¶
Note
To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.
Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .
Example 1: To register a single target with a maintenance window
The following
register-target-with-maintenance-window
example registers an instance with a maintenance window.aws ssm register-target-with-maintenance-window \ --window-id "mw-ab12cd34ef56gh78" \ --target "Key=InstanceIds,Values=i-0000293ffd8c57862" \ --owner-information "Single instance" \ --resource-type "INSTANCE"Output:
{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }Example 2: To register multiple targets with a maintenance window using instance IDs
The following
register-target-with-maintenance-window
example registers two instances with a maintenance window by specifying their instance IDs.aws ssm register-target-with-maintenance-window \ --window-id "mw-ab12cd34ef56gh78" \ --target "Key=InstanceIds,Values=i-0000293ffd8c57862,i-0cb2b964d3e14fd9f" \ --owner-information "Two instances in a list" \ --resource-type "INSTANCE"Output:
{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }Example 3: To register targets with a maintenance window using resource tags
The following
register-target-with-maintenance-window
example registers instances with a maintenance window by specifying resource tags that have been applied to the instances.aws ssm register-target-with-maintenance-window \ --window-id "mw-06cf17cbefcb4bf4f" \ --targets "Key=tag:Environment,Values=Prod" "Key=Role,Values=Web" \ --owner-information "Production Web Servers" \ --resource-type "INSTANCE"Output:
{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }Example 4: To register targets using a group of tag keys
The following
register-target-with-maintenance-window
example register instances that all have one or more tag keys assigned to them, regardless of their key values.aws ssm register-target-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --resource-type "INSTANCE" \ --target "Key=tag-key,Values=Name,Instance-Type,CostCenter"Output:
{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }Example 5: To register targets using a resource group name
The following
register-target-with-maintenance-window
example register a specified resource group, regardless of the type of resources it contains.aws ssm register-target-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --resource-type "RESOURCE_GROUP" \ --target "Key=resource-groups:Name,Values=MyResourceGroup"Output:
{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }For more information, see Register a Target Instance with the Maintenance Window (AWS CLI) in the AWS Systems Manager User Guide.
Output¶
WindowTargetId -> (string)
The ID of the target definition in this maintenance window.