AWS Systems Manager
API Reference (API Version 2014-11-06)

CreateMaintenanceWindow

Creates a new Maintenance Window.

Request Syntax

{ "AllowUnassociatedTargets": boolean, "ClientToken": "string", "Cutoff": number, "Description": "string", "Duration": number, "EndDate": "string", "Name": "string", "Schedule": "string", "ScheduleTimezone": "string", "StartDate": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

AllowUnassociatedTargets

Enables a Maintenance Window task to execute on managed instances, even if you have not registered those instances as targets. If enabled, then you must specify the unregistered instances (by instance ID) when you register a task with the Maintenance Window

If you don't enable this option, then you must specify previously-registered targets when you register a task with the Maintenance Window.

Type: Boolean

Required: Yes

ClientToken

User-provided idempotency token.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: No

Cutoff

The number of hours before the end of the Maintenance Window that Systems Manager stops scheduling new tasks for execution.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 23.

Required: Yes

Description

An optional description for the Maintenance Window. We recommend specifying a description to help you organize your Maintenance Windows.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: No

Duration

The duration of the Maintenance Window in hours.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 24.

Required: Yes

EndDate

The date and time, in ISO-8601 Extended format, for when you want the Maintenance Window to become inactive. EndDate allows you to set a date and time in the future when the Maintenance Window will no longer run.

Type: String

Required: No

Name

The name of the Maintenance Window.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 128.

Pattern: ^[a-zA-Z0-9_\-.]{3,128}$

Required: Yes

Schedule

The schedule of the Maintenance Window in the form of a cron or rate expression.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes

ScheduleTimezone

The time zone that the scheduled Maintenance Window executions are based on, in Internet Assigned Numbers Authority (IANA) format. For example: "America/Los_Angeles", "etc/UTC", or "Asia/Seoul". For more information, see the Time Zone Database on the IANA website.

Type: String

Required: No

StartDate

The date and time, in ISO-8601 Extended format, for when you want the Maintenance Window to become active. StartDate allows you to delay activation of the Maintenance Window until the specified future date.

Type: String

Required: No

Response Syntax

{ "WindowId": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

WindowId

The ID of the created Maintenance Window.

Type: String

Length Constraints: Fixed length of 20.

Pattern: ^mw-[0-9a-f]{17}$

Errors

For information about the errors that are common to all actions, see Common Errors.

IdempotentParameterMismatch

Error returned when an idempotent operation is retried and the parameters don't match the original call to the API with the same idempotency token.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

ResourceLimitExceededException

Error returned when the caller has exceeded the default resource limits. For example, too many Maintenance Windows or Patch baselines have been created.

For information about resource limits in Systems Manager, see AWS Systems Manager Limits.

HTTP Status Code: 400

Example

Sample Request

POST / HTTP/1.1 Host: ssm.us-east-2.amazonaws.com Accept-Encoding: identity Content-Length: 186 X-Amz-Target: AmazonSSM.CreateMaintenanceWindow X-Amz-Date: 20180312T201809Z User-Agent: aws-cli/1.11.180 Python/2.7.9 Windows/8 botocore/1.7.38 Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180312/us-east-2/ssm/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=39c3b3042cd2aEXAMPLE { "Cutoff": 2, "Name": "My-Maintenance-Window", "Schedule": "cron(0 12 ? * WED *)", "AllowUnassociatedTargets": true, "ClientToken": "aa1b2cde-27e3-42ff-9cac-99380EXAMPLE", "Duration": 6 }

Sample Response

{ "WindowId": "mw-0c5ed765acExample" }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: