How to manage server updates via API

Before using the API to manage your server updates, please ensure you meet the requirements for authentication described in the prerequisites below:

Prerequisites

• You have created a service account.
  (See: Create a service account)
• You have assigned the required project permissions to this service account.
  (See: Assign permissions to a service account)
• You have created an access token for this service account.
  (See: Assign authentication token to a service account)

Activate the Server Update Management Service

To activate the Server Update Management Service for a new server, send a request as shown below, including the portalProjectId, region and serverId in the URL.

POST https://server-update.api.stackit.cloud/v2/projects/{portalProjectId}/regions/{region}/servers/{serverId}/service

Activate the Server Update Management Service with a default update schedule

If you want to activate the Server Update Management Service for a new server with the default update schedule already included, first send the following request, including the portalProjectId and region in the URL to fetch the proper Update Policy ID:

GET https://server-update.api.stackit.cloud/v2/projects/{portalProjectId}/regions/{region}/update-policies

Afterwards send a request to activate the Server Update Management Service and include the portalProjectId, region, serverId and updatePolicyId in the request body:

Request

POST https://server-update.api.stackit.cloud/v2/projects/{portalProjectId}/regions/{region}/servers/{serverId}/service

{
    "updatePolicyId": "2ab33ea4-9b4b-492c-8679-3d664091c195"
}

This will activate a weekly update schedule on your server.

Run an update installation

Initiate a new update job on your server by sending a POST request to the following endpoint, providing the portalProjectId, region, serverId and a value for the maintenanceWindow:

Request

POST https://server-update.api.stackit.cloud/v2/projects/{portalprojectId}/regions/{region}/servers/{serverId}/updates

{
  "maintenanceWindow": 2
}

This request triggers the installation of updates within the specified maintenance window.

The maintenanceWindow value specifies the time frame in hours, during which the update process will begin.

Please note that the server may restart if required by the updates during this process.

Check the status and results of the update job

To monitor the progress and results of the update, use the following GET request, providing the portalProjectId, region, serverId and updateId, which is displayed in the response of the initiated update job:

Request

GET https://server-update.api.stackit.cloud/v2/projects/{portalprojectId}/regions/{region}/servers/{serverId}/updates/{updateId}

Create an update schedule

When you are creating update schedules, you have to provide recurrence rules for calendar dates in the rrule field according to the Internet Calendaring and Scheduling Core Object Specification (iCalendar RFC5545).

Please find below an example of the request which needs to be sent with provided portalProjectId, region, serverId, rrule and the maintenanceWindow:

Request

POST https://server-update.api.stackit.cloud/v2/projects/{portalprojectId}/regions/{region}/servers/{serverId}/update-schedules

{
  "name": "Default Update Schedule",
 "rrule": "DTSTART;TZID=Europe/Sofia:20200803T134000 RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SA",
  "enabled": true,
  "maintenanceWindow": 2
}

The full API documentation, including all available endpoints and examples, is available here: STACKIT Server Update Management API