Manage Encryption at Rest on a dedicated server with the API
Find out how to check eligibility, enable or disable Encryption at Rest and follow the operation on an OVHcloud Dedicated Server with the OVHcloud API v2
Objective
The OVHcloud API v2 lets you automate Encryption at Rest on your Dedicated Servers. This guide explains how to check that a server accepts Encryption at Rest, enable or disable it, and follow the operation with the OVHcloud API.
The encryption key stays inside each disk. OVHcloud manages the passphrase that unlocks the disks, and it is never sent to you. Using your own keys is not available. For more information, read What is Encryption at Rest on a dedicated server?
Enabling and disabling Encryption at Rest both erase all the data on the server. Disabling cryptographically erases the disks: there is no in-place decryption. In both cases, the operating system must be reinstalled afterwards. The API asks for no confirmation: the request alone starts the operation. Back up your data first.
Requirements
- A Dedicated Server on an eligible range and in an eligible region (see Encryption at Rest requirements and limitations)
- Access to the OVHcloud API v2 (see OVHcloud API v2 - Principles of operation)
- A backup of your data
Introduction
On the API v2, a Dedicated Server is a resource with two views of its configuration:
targetSpecis the state you request.currentStateis the state actually applied on the server.
You change the configuration by sending a new targetSpec along with the resource's checksum. OVHcloud then applies it asynchronously and reports progress in currentTasks and resourceStatus.
Encryption at Rest is not available in the OVHcloud Terraform provider.
Instructions
This section covers the three steps of the operation: check, request, follow.
Step 1 - Checking that the server accepts the operation
Read the server and ask for the availability of its actions:
Without actions=true, the response does not contain currentState.actions. This absence means the information was not requested, not that the action is unavailable.
The ENABLE_ENCRYPTION_AT_REST entry of currentState.actions carries a status:
Each reason in blockedBy has a code and a nature:
Example response (extract):
Note the checksum returned in the same response: you need it in the next step.
Step 2 - Enabling or disabling Encryption at Rest
Send the target state with the checksum from your last read. Two methods are available:
PATCHchanges only the features you name. Use it to change Encryption at Rest alone.PUTreplaces the whole target specification: every feature must be present in the body.
With PATCH, use the following API call and body:
With PUT, use the following API call:
The body has the same shape, with every feature of targetSpec.features filled in.
The response returns the server with resourceStatus set to UPDATING and the operation listed in currentTasks, with the type ENCRYPTION_AT_REST_TARGET_SPEC_UPDATE.
Step 3 - Following the operation
Read the server again with the same GET request, as often as needed. The operation can take up to 24Â hours from end to end, and longer if an intervention in the datacentre is needed. In that case, you also receive the usual emails when the intervention is opened and when it is closed.
The operation is complete when resourceStatus is READY and currentState matches targetSpec. When the operation succeeds, the server restarts in rescue mode and you receive the usual rescue-mode email. Then reinstall the operating system (see Install an OS via the OVHcloud API on a Dedicated Server).
If the operation fails, currentState keeps its previous value, targetSpec keeps your request, and no task remains in progress. Send the request again, with the checksum from your last read, to retry.
The task link returned in currentTasks does not open a detailed task view yet. Follow the operation by reading the server.
Errors
The table below lists the errors you may receive when you request the operation, and what to do about each one.
Go further
What is Encryption at Rest on a dedicated server?
Encryption at Rest requirements and limitations
Encryption at Rest on dedicated servers: FAQ
Join our community of users.