Maintenance windows API - PUT a maintenance window
Updates the specified maintenance window. If a maintenance window with the specified ID doesn't exist, a new one is created.
The request consumes and produces an application/json
payload.
PUT |
|
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
id | string |
The ID of the maintenance window to be updated. |
path | required |
body | MaintenanceWindow |
The JSON body of the request. Contains updated parameters of the maintenance window. |
body | optional |
The MaintenanceWindow object
Configuration of a maintenance window.
Element | Type | Description | Required |
---|---|---|---|
metadata | ConfigurationMetadata |
Metadata useful for debugging. |
optional |
id | string |
The ID of the maintenance window. |
optional |
name | string |
The name of the maintenance window, displayed in the UI. |
required |
description | string |
A short description of the maintenance purpose. |
required |
type | string |
The type of the maintenance: planned or unplanned. The type element can hold these values. |
required |
suppression | string |
The type of suppression of alerting and problem detection during the maintenance. The suppression element can hold these values. |
required |
scope | Scope |
The scope of the maintenance window. The scope restricts the alert/problem detection suppression to certain DESK entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope. If no scope is specified, the alert/problem detection suppression applies to the entire environment. |
optional |
schedule | Schedule |
The date, time, and recurrence of the maintenance window. |
required |
The Schedule object
The schedule of the maintenance window.
Element | Type | Description | Required |
---|---|---|---|
recurrenceType | string |
The type of the schedule recurrence. The recurrenceType element can hold these values. |
required |
recurrence | Recurrence |
The recurrence of the schedule. Not applicable if recurrenceType is |
optional |
start | string |
The start date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format. |
required |
end | string |
The end date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format. |
required |
zoneId | string |
The time zone of the start and end time. Default time zone is UTC. You can use either UTC offset |
required |
The Recurrence object
The recurrence of the maintenance window.
Element | Type | Description | Required |
---|---|---|---|
dayOfWeek | string |
The day of the week for weekly maintenance. The format is the full name of the day in upper case, for example |
optional |
dayOfMonth | integer |
The day of the month for monthly maintenance. The value of |
optional |
startTime | string |
The start time of the maintenance window in HH:mm format. |
required |
durationMinutes | integer |
The duration of the maintenance window in minutes. |
required |
The Scope object
The scope of the maintenance window.
The scope restricts the alert/problem detection suppression to certain DESK entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope.
If no scope is specified, the alert/problem detection suppression applies to the entire environment.
Element | Type | Description | Required |
---|---|---|---|
entities | string[] |
A list of DESK entities (for example, hosts or services) to be included in the scope. Allowed values are DESK entity IDs. |
required |
matches | MonitoredEntityFilter[] |
A list of matching rules for dynamic scope formation. If several rules are set, the OR logic applies. |
required |
The MonitoredEntityFilter object
A matching rule for DESK entities.
Element | Type | Description | Required |
---|---|---|---|
type | string |
The type of the DESK entities (for example, hosts or services) you want to pick up by matching. The type element can hold these values. |
optional |
managementZoneId | integer |
The ID of a management zone to which the matched entities must belong. |
optional |
tags | TagInfo[] |
The tag you want to use for matching. You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables. |
required |
tagCombination | string |
The logic that applies when several tags are specified: AND/OR. If not set, the OR logic is used. The tagCombination element can hold these values. |
optional |
The TagInfo object
Tag of a DESK entity.
Element | Type | Description | Required |
---|---|---|---|
context | string |
The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the |
required |
key | string |
The key of the tag. Custom tags have the tag value here. |
required |
value | string |
The value of the tag. Not applicable to custom tags. |
optional |
The ConfigurationMetadata object
Metadata useful for debugging
Element | Type | Description | Required |
---|---|---|---|
configurationVersions | integer[] |
A Sorted list of the version numbers of the configuration. |
optional |
clusterVersion | string |
DESK server version. |
optional |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.
{
"metadata": {
"configurationVersions": [
4,
2
],
"clusterVersion": {
"major": 0,
"minor": 0,
"revision": 0,
"sourceRevision": "",
"timestamp": ""
}
},
"name": "Example Window",
"description": "An example Maintenance window\n",
"type": "UNPLANNED",
"suppression": "DETECT_PROBLEMS_AND_ALERT",
"scope": {
"entities": [
"HOST-0000000000123456"
],
"matches": [
{
"type": "HOST",
"managementZoneId": 123456789,
"tags": [
{
"key": "testkey",
"value": "testvalue",
"context": "AWS"
}
],
"tagCombination": "AND"
}
]
},
"schedule": {
"recurrenceType": "MONTHLY",
"recurrence": {
"dayOfMonth": "23",
"startTime": "16:28",
"durationMinutes": "60"
},
"start": "2018-08-02 00:00",
"end": "2019-02-27 00:00",
"zoneId": "Europe/Vienna"
}
}
Possible values
Possible values for the dayOfWeek element in the Recurrence object:
- FRIDAY
- MONDAY
- SATURDAY
- SUNDAY
- THURSDAY
- TUESDAY
- WEDNESDAY
Possible values for the recurrenceType element in the Schedule object:
- DAILY
- MONTHLY
- ONCE
- WEEKLY
Possible values for the tagCombination element in the MonitoredEntityFilter object:
- AND
- OR
Possible values for the context element in the TagInfo object:
- AWS
- AWS_GENERIC
- AZURE
- CLOUD_FOUNDRY
- CONTEXTLESS
- ENVIRONMENT
- GOOGLE_CLOUD
- KUBERNETES
Possible values for the type element in the MonitoredEntityFilter object:
- APPLICATION
- APPLICATION_METHOD
- APPLICATION_METHOD_GROUP
- AUTO_SCALING_GROUP
- AUXILIARY_SYNTHETIC_TEST
- AWS_APPLICATION_LOAD_BALANCER
- AWS_AVAILABILITY_ZONE
- AWS_CREDENTIALS
- AWS_LAMBDA_FUNCTION
- AWS_NETWORK_LOAD_BALANCER
- AZURE_API_MANAGEMENT_SERVICE
- AZURE_APPLICATION_GATEWAY
- AZURE_COSMOS_DB
- AZURE_CREDENTIALS
- AZURE_EVENT_HUB
- AZURE_EVENT_HUB_NAMESPACE
- AZURE_FUNCTION_APP
- AZURE_IOT_HUB
- AZURE_LOAD_BALANCER
- AZURE_MGMT_GROUP
- AZURE_REDIS_CACHE
- AZURE_REGION
- AZURE_SERVICE_BUS_NAMESPACE
- AZURE_SERVICE_BUS_QUEUE
- AZURE_SERVICE_BUS_TOPIC
- AZURE_SQL_DATABASE
- AZURE_SQL_ELASTIC_POOL
- AZURE_SQL_SERVER
- AZURE_STORAGE_ACCOUNT
- AZURE_SUBSCRIPTION
- AZURE_TENANT
- AZURE_VM
- AZURE_VM_SCALE_SET
- AZURE_WEB_APP
- CF_APPLICATION
- CF_FOUNDATION
- CINDER_VOLUME
- CUSTOM_APPLICATION
- CUSTOM_DEVICE
- CUSTOM_DEVICE_GROUP
- DCRUM_APPLICATION
- DCRUM_SERVICE
- DCRUM_SERVICE_INSTANCE
- DISK
- DOCKER_CONTAINER_GROUP_INSTANCE
- DYNAMO_DB_TABLE
- EBS_VOLUME
- EC2_INSTANCE
- ELASTIC_LOAD_BALANCER
- ENVIRONMENT
- EXTERNAL_SYNTHETIC_TEST_STEP
- GCP_ZONE
- GEOLOCATION
- GEOLOC_SITE
- GOOGLE_COMPUTE_ENGINE
- HOST
- HOST_GROUP
- HTTP_CHECK
- HTTP_CHECK_STEP
- HYPERVISOR
- KUBERNETES_CLUSTER
- KUBERNETES_NODE
- MOBILE_APPLICATION
- NETWORK_INTERFACE
- NEUTRON_SUBNET
- OPENSTACK_PROJECT
- OPENSTACK_REGION
- OPENSTACK_VM
- OS
- PROCESS_GROUP
- PROCESS_GROUP_INSTANCE
- RELATIONAL_DATABASE_SERVICE
- SERVICE
- SERVICE_INSTANCE
- SERVICE_METHOD
- SERVICE_METHOD_GROUP
- SWIFT_CONTAINER
- SYNTHETIC_LOCATION
- SYNTHETIC_TEST
- SYNTHETIC_TEST_STEP
- VIRTUALMACHINE
- VMWARE_DATACENTER
Possible values for the suppression element in the MaintenanceWindow object:
- DETECT_PROBLEMS_AND_ALERT
- DETECT_PROBLEMS_DONT_ALERT
- DONT_DETECT_PROBLEMS
Possible values for the type element in the MaintenanceWindow object:
- PLANNED
- UNPLANNED
Response format
The EntityShortRepresentation object
The short representation of a DESK entity.
Element | Type | Description |
---|---|---|
id | string | The ID of the DESK entity. |
name | string | The name of the DESK entity. |
description | string | A short description of the DESK entity. |
{}
Response codes
Code | Description |
---|---|
201 | Success. The new maintenance window has been created. The response body contains its ID. |
204 | Success. The maintenance window has been updated. The response doesn't have a body. |
400 | Failed. The input is invalid. |
Validate payload
We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.
POST |
|
Response codes
Code | Description |
---|---|
204 | Validated. The submitted configuration is valid. Response doesn't have a body |
400 | Failed. The input is invalid. |
Example
In this example, the request updates the infrastructure maintenance maintenance window from the GET request example
The initial configuration is the following:
The request changes the recurrence to weekly maintenance on Mondays. It also adds hosts with tags TestWindows and TestLinux to the scope.
The API token is passed in the Authorization header.
The request body is lengthy, so it is truncated in the Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own.
Curl
curl -X PUT \
https://mySampleEnv.live.dexp.ae/api/config/v1/maintenanceWindows/0b989446-e56f-4837-a521-96f4d39a9b76 \
-H 'Authorization: Api-token abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
-d '{ <truncated - see the Request body section > }'
Request URL
https://mySampleEnv.live.dexp.ae/api/config/v1/maintenanceWindows/0b989446-e56f-4837-a521-96f4d39a9b76
Request body
api-examples/config/mw/put-mw.json
{
"name": "infrastructure maintenance",
"description": "Weekly check-up of infrastructure",
"type": "PLANNED",
"suppression": "DETECT_PROBLEMS_DONT_ALERT",
"scope": {
"entities": [],
"matches": [
{
"type": "HOST",
"managementZoneId": null,
"tags": [
{
"context": "CONTEXTLESS",
"key": "InfWindows"
},
{
"context": "CONTEXTLESS",
"key": "InfLinux"
},
{
"context": "CONTEXTLESS",
"key": "TestWindows"
},
{
"context": "CONTEXTLESS",
"key": "TestLinux"
}
],
"tagCombination": "OR"
}
]
},
"schedule": {
"recurrenceType": "WEEKLY",
"recurrence": {
"dayOfWeek": "MONDAY",
"startTime": "19:00",
"durationMinutes": 60
},
"start": "2019-07-01 00:00",
"end": "2020-07-31 23:59",
"zoneId": "Europe/Vienna"
}
}
Response code
204
Result
The updated maintenance window has the following parameters: