Skip to main content

maintenance_window_tasks

Creates, updates, deletes, gets or lists a maintenance_window_tasks resource.

Overview​

Namemaintenance_window_tasks
TypeResource
Idaws.ssm.maintenance_window_tasks

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
alarm_configurationobjectThe details for the CloudWatch alarm you want to apply to an automation or command.
cutoff_behaviorstringThe action to take on tasks when the maintenance window cutoff time is reached. CONTINUE_TASK means that tasks continue to run. For Automation, Lambda, Step Functions tasks, CANCEL_TASK means that currently running task invocations continue, but no new task invocations are started. For Run Command tasks, CANCEL_TASK means the system attempts to stop the task by sending a CancelCommand operation. (CONTINUE_TASK, CANCEL_TASK)
descriptionstringThe retrieved task description.
logging_infoobjectThe location in Amazon Simple Storage Service (Amazon S3) where the task results are logged. LoggingInfo has been deprecated. To specify an Amazon Simple Storage Service (Amazon S3) bucket to contain logs, instead use the OutputS3BucketName and OutputS3KeyPrefix options in the TaskInvocationParameters structure. For information about how Amazon Web Services Systems Manager handles these options for the supported maintenance window task types, see MaintenanceWindowTaskInvocationParameters.
max_concurrencystringThe maximum number of targets allowed to run this task in parallel. For maintenance window tasks without a target specified, you can't supply a value for this option. Instead, the system inserts a placeholder value of 1, which may be reported in the response to this command. This value doesn't affect the running of your task and can be ignored. (pattern: <code>^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$</code>)
max_errorsstringThe maximum number of errors allowed before the task stops being scheduled. For maintenance window tasks without a target specified, you can't supply a value for this option. Instead, the system inserts a placeholder value of 1, which may be reported in the response to this command. This value doesn't affect the running of your task and can be ignored. (pattern: <code>^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$</code>)
namestringThe retrieved task name. (pattern: <code>^[a-zA-Z0-9_-.]{3,128}$</code>)
priorityintegerThe priority of the task when it runs. The lower the number, the higher the priority. Tasks that have the same priority are scheduled in parallel.
service_role_arnstringThe Amazon Resource Name (ARN) of the IAM service role for Amazon Web Services Systems Manager to assume when running a maintenance window task. If you do not specify a service role ARN, Systems Manager uses a service-linked role in your account. If no appropriate service-linked role for Systems Manager exists in your account, it is created when you run RegisterTaskWithMaintenanceWindow. However, for an improved security posture, we strongly recommend creating a custom policy and custom service role for running your maintenance window tasks. The policy can be crafted to provide only the permissions needed for your particular maintenance window tasks. For more information, see Setting up Maintenance Windows in the in the Amazon Web Services Systems Manager User Guide.
targetsarrayThe targets where the task should run.
task_arnstringThe resource that the task used during execution. For RUN_COMMAND and AUTOMATION task types, the value of TaskArn is the SSM document name/ARN. For LAMBDA tasks, the value is the function name/ARN. For STEP_FUNCTIONS tasks, the value is the state machine ARN.
task_invocation_parametersobjectThe parameters to pass to the task when it runs.
task_parametersobjectThe parameters to pass to the task when it runs. TaskParameters has been deprecated. To specify parameters to pass to a task when it runs, instead use the Parameters option in the TaskInvocationParameters structure. For information about how Systems Manager handles these options for the supported maintenance window task types, see MaintenanceWindowTaskInvocationParameters.
task_typestringThe type of task to run. (RUN_COMMAND, AUTOMATION, STEP_FUNCTIONS, LAMBDA)
window_idstringThe retrieved maintenance window ID. (pattern: <code>^mw-[0-9a-f]{17}$</code>)
window_task_idstringThe retrieved maintenance window task ID. (pattern: <code>^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$</code>)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_maintenance_window_taskselectregionRetrieves the details of a maintenance window task. For maintenance window tasks without a specified target, you can't supply values for --max-errors and --max-concurrency. Instead, the system inserts a placeholder value of 1, which may be reported in the response to this command. These values don't affect the running of your task and can be ignored. To retrieve a list of tasks in a maintenance window, instead use the DescribeMaintenanceWindowTasks command.
describe_maintenance_window_tasksselectregionLists the tasks in a maintenance window. For maintenance window tasks without a specified target, you can't supply values for --max-errors and --max-concurrency. Instead, the system inserts a placeholder value of 1, which may be reported in the response to this command. These values don't affect the running of your task and can be ignored.
update_maintenance_window_taskupdateregion, WindowId, WindowTaskIdModifies a task assigned to a maintenance window. You can't change the task type, but you can change the following values: TaskARN. For example, you can change a RUN_COMMAND task from AWS-RunPowerShellScript to AWS-RunShellScript. ServiceRoleArn TaskInvocationParameters Priority MaxConcurrency MaxErrors 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. If the value for a parameter in UpdateMaintenanceWindowTask is null, then the corresponding field isn't modified. If you set Replace to true, then all fields required by the RegisterTaskWithMaintenanceWindow operation are required for this request. Optional fields that aren't specified are set to null. When you update a maintenance window task that has options specified in TaskInvocationParameters, you must provide again all the TaskInvocationParameters values that you want to retain. The values you don't specify again are removed. For example, suppose that when you registered a Run Command task, you specified TaskInvocationParameters values for Comment, NotificationConfig, and OutputS3BucketName. If you update the maintenance window task and specify only a different OutputS3BucketName value, the values for Comment and NotificationConfig are removed.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Retrieves the details of a maintenance window task. For maintenance window tasks without a specified target, you can't supply values for --max-errors and --max-concurrency. Instead, the system inserts a placeholder value of 1, which may be reported in the response to this command. These values don't affect the running of your task and can be ignored. To retrieve a list of tasks in a maintenance window, instead use the DescribeMaintenanceWindowTasks command.

SELECT
alarm_configuration,
cutoff_behavior,
description,
logging_info,
max_concurrency,
max_errors,
name,
priority,
service_role_arn,
targets,
task_arn,
task_invocation_parameters,
task_parameters,
task_type,
window_id,
window_task_id
FROM aws.ssm.maintenance_window_tasks
WHERE region = '{{ region }}' -- required
;

UPDATE examples​

Modifies a task assigned to a maintenance window. You can't change the task type, but you can change the following values: TaskARN. For example, you can change a RUN_COMMAND task from AWS-RunPowerShellScript to AWS-RunShellScript. ServiceRoleArn TaskInvocationParameters Priority MaxConcurrency MaxErrors 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. If the value for a parameter in UpdateMaintenanceWindowTask is null, then the corresponding field isn't modified. If you set Replace to true, then all fields required by the RegisterTaskWithMaintenanceWindow operation are required for this request. Optional fields that aren't specified are set to null. When you update a maintenance window task that has options specified in TaskInvocationParameters, you must provide again all the TaskInvocationParameters values that you want to retain. The values you don't specify again are removed. For example, suppose that when you registered a Run Command task, you specified TaskInvocationParameters values for Comment, NotificationConfig, and OutputS3BucketName. If you update the maintenance window task and specify only a different OutputS3BucketName value, the values for Comment and NotificationConfig are removed.

UPDATE aws.ssm.maintenance_window_tasks
SET 
WindowId = '{{ WindowId }}',
WindowTaskId = '{{ WindowTaskId }}',
Targets = '{{ Targets }}',
TaskArn = '{{ TaskArn }}',
ServiceRoleArn = '{{ ServiceRoleArn }}',
TaskParameters = '{{ TaskParameters }}',
TaskInvocationParameters = '{{ TaskInvocationParameters }}',
Priority = {{ Priority }},
MaxConcurrency = '{{ MaxConcurrency }}',
MaxErrors = '{{ MaxErrors }}',
LoggingInfo = '{{ LoggingInfo }}',
Name = '{{ Name }}',
Description = '{{ Description }}',
Replace = {{ Replace }},
CutoffBehavior = '{{ CutoffBehavior }}',
AlarmConfiguration = '{{ AlarmConfiguration }}'
WHERE 
region = '{{ region }}' --required
AND WindowId = '{{ WindowId }}' --required
AND WindowTaskId = '{{ WindowTaskId }}' --required
RETURNING
alarm_configuration,
cutoff_behavior,
description,
logging_info,
max_concurrency,
max_errors,
name,
priority,
service_role_arn,
targets,
task_arn,
task_invocation_parameters,
task_parameters,
window_id,
window_task_id;
Last updated on