Skip to content
AWS for Query.Farm

aws.ssm.get_maintenance_window_task

Example SQL Queries

SELECT * FROM
aws.ssm.get_maintenance_window_task
WHERE
"window_id" = 'VALUE'
AND "window_task_id" = 'VALUE';

Description

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.

Table Definition

Column NameColumn Data Type
window_id Required Input Column

The retrieved maintenance window ID.

VARCHAR
window_task_id Required Input Column

The retrieved maintenance window task ID.

VARCHAR
_aws_profile Input Column

The AWS profile defines the AWS identity used. It can be defined via credentials or by assuming a IAM role.

STRUCT(
    "type" VARCHAR,
    "name" VARCHAR,
    "account_id" VARCHAR,
    "via_profile_name" VARCHAR,
    "assumed_role_arn" VARCHAR,
    "organization" STRUCT(
        "account_name" VARCHAR,
        "id" VARCHAR,
        "tags" STRUCT(
            "key" VARCHAR,
            "value" VARCHAR
        )[],
        "master_account" STRUCT(
            "id" VARCHAR,
            "email" VARCHAR
        ),
        "parents" STRUCT(
            "type" VARCHAR,
            "id" VARCHAR,
            "name" VARCHAR,
            "tags" STRUCT(
                "key" VARCHAR,
                "value" VARCHAR
            )[]
        )[]
    )
)
Show child fields
_aws_profile.account_id

The AWS account id

_aws_profile.assumed_role_arn

The ARN of the assumed role

_aws_profile.name

The unique name of the profile.

_aws_profile.organization

Information about this profile's membership in the AWS organization.

Show child fields
_aws_profile.organization.account_name

The name of account speciifed by the organization

_aws_profile.organization.id

The organization id

_aws_profile.organization.master_account
Show child fields
_aws_profile.organization.master_account.email

The organization master account email address

_aws_profile.organization.master_account.id

The organization master account id

_aws_profile.organization.parents[]
Show child fields
_aws_profile.organization.parents[].id

The id of the parent

_aws_profile.organization.parents[].name

The name of the parent

_aws_profile.organization.parents[].tags[]
Show child fields
_aws_profile.organization.parents[].tags[].key
_aws_profile.organization.parents[].tags[].value
_aws_profile.organization.parents[].type

The type of parent can be an organization unit or a root

_aws_profile.organization.tags[]
Show child fields
_aws_profile.organization.tags[].key
_aws_profile.organization.tags[].value
_aws_profile.type

The type of profile, either 'credentials' or 'assumed_role'

_aws_profile.via_profile_name

This IAM role for this profile is assumed by first utilizing another profile with this name to obtain credentials.

_aws_region Input Column

The AWS region to use.

VARCHAR
alarm_configuration

The details for the CloudWatch alarm you applied to your maintenance window task.

STRUCT(
    "ignore_poll_alarm_failure" BOOLEAN,
    "alarms" STRUCT(
        "name" VARCHAR
    )[]
)
Show child fields
alarm_configuration.alarms[]
Show child fields
alarm_configuration.alarms[].name

The name of your CloudWatch alarm.

alarm_configuration.ignore_poll_alarm_failure

When this value is true, your automation or command continues to run in cases where we can’t retrieve alarm status information from CloudWatch. In cases where we successfully retrieve an alarm status of OK or INSUFFICIENT_DATA, the automation or command continues to run, regardless of this value. Default is false.

cutoff_behavior

The 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.

VARCHAR
description

The retrieved task description.

VARCHAR
logging_info

The 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.

STRUCT(
    "s3_bucket_name" VARCHAR,
    "s3_key_prefix" VARCHAR,
    "s3_region" VARCHAR
)
Show child fields
logging_info.s3_bucket_name

The name of an S3 bucket where execution logs are stored.

logging_info.s3_key_prefix

(Optional) The S3 bucket subfolder.

logging_info.s3_region

The Amazon Web Services Region where the S3 bucket is located.

max_concurrency

The 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.

VARCHAR
max_errors

The 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.

VARCHAR
name

The retrieved task name.

VARCHAR
priority

The 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.

BIGINT
service_role_arn

The 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.

VARCHAR
targets

The targets where the task should run.

STRUCT(
    "key" VARCHAR,
    "values" VARCHAR[]
)[]
Show child fields
targets[]
Show child fields
targets[].key

User-defined criteria for sending commands that target managed nodes that meet the criteria.

targets[].values[]
task_arn

The 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.

VARCHAR
task_invocation_parameters

The parameters to pass to the task when it runs.

STRUCT(
    "run_command" STRUCT(
        "comment" VARCHAR,
        "cloud_watch_output_config" STRUCT(
            "cloud_watch_log_group_name" VARCHAR,
            "cloud_watch_output_enabled" BOOLEAN
        ),
        "document_hash" VARCHAR,
        "document_hash_type" VARCHAR,
        "document_version" VARCHAR,
        "notification_config" STRUCT(
            "notification_arn" VARCHAR,
            "notification_events" VARCHAR[],
            "notification_type" VARCHAR
        ),
        "output_s3_bucket_name" VARCHAR,
        "output_s3_key_prefix" VARCHAR,
        "parameters" MAP(VARCHAR, VARCHAR[]),
        "service_role_arn" VARCHAR,
        "timeout_seconds" BIGINT
    ),
    "automation" STRUCT(
        "document_version" VARCHAR,
        "parameters" MAP(VARCHAR, VARCHAR[])
    ),
    "step_functions" STRUCT(
        "input" VARCHAR,
        "name" VARCHAR
    ),
    "lambda" STRUCT(
        "client_context" VARCHAR,
        "qualifier" VARCHAR,
        "payload" BLOB
    )
)
Show child fields
task_invocation_parameters.automation

The parameters for an AUTOMATION task type.

Show child fields
task_invocation_parameters.automation.document_version

The version of an Automation runbook to use during task execution.

task_invocation_parameters.automation.parameters

The parameters for the AUTOMATION task.

For information about specifying and updating task parameters, see RegisterTaskWithMaintenanceWindow and UpdateMaintenanceWindowTask.

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.

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.

For AUTOMATION task types, Amazon Web Services Systems Manager ignores any values specified for these parameters.

task_invocation_parameters.lambda

The parameters for a LAMBDA task type.

Show child fields
task_invocation_parameters.lambda.client_context

Pass client-specific information to the Lambda function that you are invoking. You can then process the client information in your Lambda function as you choose through the context variable.

task_invocation_parameters.lambda.payload

JSON to provide to your Lambda function as input.

task_invocation_parameters.lambda.qualifier

(Optional) Specify an Lambda function version or alias name. If you specify a function version, the operation uses the qualified function Amazon Resource Name (ARN) to invoke a specific Lambda function. If you specify an alias name, the operation uses the alias ARN to invoke the Lambda function version to which the alias points.

task_invocation_parameters.run_command

The parameters for a RUN_COMMAND task type.

Show child fields
task_invocation_parameters.run_command.cloud_watch_output_config

Configuration options for sending command output to Amazon CloudWatch Logs.

Show child fields
task_invocation_parameters.run_command.cloud_watch_output_config.cloud_watch_log_group_name

The name of the CloudWatch Logs log group where you want to send command output. If you don't specify a group name, Amazon Web Services Systems Manager automatically creates a log group for you. The log group uses the following naming format:

aws/ssm/SystemsManagerDocumentName

task_invocation_parameters.run_command.cloud_watch_output_config.cloud_watch_output_enabled

Enables Systems Manager to send command output to CloudWatch Logs.

task_invocation_parameters.run_command.comment

Information about the commands to run.

task_invocation_parameters.run_command.document_hash

The SHA-256 or SHA-1 hash created by the system when the document was created. SHA-1 hashes have been deprecated.

task_invocation_parameters.run_command.document_hash_type

SHA-256 or SHA-1. SHA-1 hashes have been deprecated.

task_invocation_parameters.run_command.document_version

The Amazon Web Services Systems Manager document (SSM document) version to use in the request. You can specify $DEFAULT, $LATEST, or a specific version number. If you run commands by using the Amazon Web Services CLI, then you must escape the first two options by using a backslash. If you specify a version number, then you don't need to use the backslash. For example:

--document-version "\$DEFAULT"

--document-version "\$LATEST"

--document-version "3"

task_invocation_parameters.run_command.notification_config

Configurations for sending notifications about command status changes on a per-managed node basis.

Show child fields
task_invocation_parameters.run_command.notification_config.notification_arn

An Amazon Resource Name (ARN) for an Amazon Simple Notification Service (Amazon SNS) topic. Run Command pushes notifications about command status changes to this topic.

task_invocation_parameters.run_command.notification_config.notification_events[]
task_invocation_parameters.run_command.notification_config.notification_type

The type of notification.

  • Command: Receive notification when the status of a command changes.

  • Invocation: For commands sent to multiple managed nodes, receive notification on a per-node basis when the status of a command changes.

task_invocation_parameters.run_command.output_s3_bucket_name

The name of the Amazon Simple Storage Service (Amazon S3) bucket.

task_invocation_parameters.run_command.output_s3_key_prefix

The S3 bucket subfolder.

task_invocation_parameters.run_command.parameters

The parameters for the RUN_COMMAND task execution.

task_invocation_parameters.run_command.service_role_arn

The 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.

task_invocation_parameters.run_command.timeout_seconds

If this time is reached and the command hasn't already started running, it doesn't run.

task_invocation_parameters.step_functions

The parameters for a STEP_FUNCTIONS task type.

Show child fields
task_invocation_parameters.step_functions.input

The inputs for the STEP_FUNCTIONS task.

task_invocation_parameters.step_functions.name

The name of the STEP_FUNCTIONS task.

task_parameters

The 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.

MAP(VARCHAR, STRUCT(
        "values" VARCHAR[]
    ))
task_type

The type of task to run.

VARCHAR