Maintenance Windows

Last modified on April 16, 2024

This article describes how to set a maintenance window for nodes (gateways and relays). Scheduling a maintenance window allows you to have some control over the hour of the day when node upgrades happen. If a custom maintenance window is not specified, the default window of 7:00 Coordinated Universal Time (UTC) daily applies.

All nodes have a maintenance window and follow a standard process for upgrades:

  1. When a node is notified of a new version and it has no client connections, it updates itself immediately unless a custom schedule using cron notation has been set.
  2. If a node does have client connections, however, it enters the state “Awaiting Restart” and updates as soon as client connections drop to zero. If that doesn’t happen before the maintenance window is reached, the gateway or relay terminates all connections, updates, and restarts with the new version. The default maintenance window is 7:00 UTC.

How to Schedule Maintenance Windows

There are several ways to schedule maintenance windows. You can configure simple daily maintenance windows using an environment variable or in the YAML configuration for a container. You can also use options when starting a node via the CLI to set either a simple daily maintenance window, or a schedule(s) of cron-based weekly maintenance window(s).

The method you choose depends on your setup and what is easiest for you:

Configure weekly schedules remotely

You may use cron notation to configure routine node update window(s) to take place on a weekly basis. These schedules must be semicolon-separated. The first group listed will indicate the time window in which the node will cut off connections, restart, and update, no matter the load on the node. The other schedules listed will be windows in which the gateway or relay will restart and update if it is currently serving no traffic and updates are available.

This command may be run remotely at the CLI using the ID of the node in question, and when the node updates, it will use the set schedule(s).

Because gateways and relays are required to have at least one maintenance window available each week, the values for the month and day_of_month fields in the cron-formatted schedule will be rejected if not set to *. The notation should be in the following format:

sdm admin relays update --maintenance-windows="<CRON_SCHEDULE>;<SECONDARY_CRON_SCHEDULES>" <GATEWAY_ID>

Example:

sdm admin relays update --maintenance-windows="* 7 * * 0,6;* * * * *" n-56988fae64a73652

In this example (according to the first cron schedule) the gateway or relay will forcibly restart and update (if updates are available) at 7:00 on Saturdays and Sundays. Optionally (according to the second schedule) if there are updates available any hour of any day of the week when the gateway or relay is not under load, it will restart and update.

Configure a daily window with the CLI

To set an hour each day that the node will be available to restart and update, you can use the --maintenance-window-start option when starting or updating the node. Replace <VALUE> in the example with an integer representing the UTC hour (0-23) that you would like to set as your maintenance window:

sdm relay --maintenance-window-start <VALUE>

Example:

sdm relay --maintenance-window-start 15

In the example shown, the value is set to 15. If the node is not under load when a new version releases, it restarts and updates. If it is under load when a new version releases, the maintenance window starts at 15:00 UTC. At that time, the node starts terminating client connections, restarts, and updates.

Configure a daily window with an environment variable

If your node is installed on a Linux host, we recommend that you use the environment variable method to set a maintenance window:

  1. Install your node using our default Linux node instructions. Doing so installs a systemd .service unit file and an environment file.

  2. Open the environment file for editing. The default location is /etc/sysconfig/sdm-proxy.

  3. Add a new line with the SDM_MAINTENANCE_WINDOW_START variable, formatted as an integer, representing the UTC hour (0-23) that you would like to set as your maintenance window:

    SDM_RELAY_TOKEN=[redacted]
SDM_MAINTENANCE_WINDOW_START=15

  1. Save the file.

  2. Run the following to pick up the update:

    systemctl daemon-reload

  3. Restart the gateway or relay service:

    systemctl restart sdm-proxy.service

Configure a daily window for containers with YAML

If you are using YAML to deploy the StrongDM Gateway image in a container, you can set a maintenance window by using the SDM_MAINTENANCE_WINDOW_START environment variable formatted as an integer representing the UTC hour (0-23) that you would like to set as your maintenance window:

spec: null
containers:
  - name: sdm-relay
image: 'quay.io/sdmrepo/relay:latest'
imagePullPolicy: Always
environment:
  - SDM_RELAY_TOKEN=[redacted]
  - "SDM_ORCHESTRATOR_PROBES=:9090"
  - SDM_MAINTENANCE_WINDOW_START=15

In the example shown, the environment variable sets a maintenance window at 15 UTC.