For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/pt/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/pt/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/pt/guides/bare-metal-cloud/dedicated-servers/encryption-at-rest-api.md.
Ir para o conteúdo

Manage Encryption at Rest on a dedicated server with the API

Ver como Markdown

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.

Info

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?

Danger

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

Introduction

On the API v2, a Dedicated Server is a resource with two views of its configuration:

  • targetSpec is the state you request.
  • currentState is 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:

ParameterRequiredDescriptionExample
serviceNameYesService name of the Dedicated Server.ns1234567.ip-203-0-113.eu
actionsNoSet to true to return currentState.actions.true

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:

statusMeaning
AVAILABLEThe server accepts the operation now.
UNAVAILABLEThe server refuses the operation. blockedBy lists every reason.
UNDETERMINEDNothing known blocks the operation, but one check could not be completed. You can still send the request.

Each reason in blockedBy has a code and a nature:

codenatureMeaning
NOT_ELIGIBLEPERMANENTThe server does not offer Encryption at Rest.
EXCLUSIVE_OPERATION_RUNNINGTRANSIENTAnother operation is running on the server. details.operationId identifies it. Try again once it has finished.

Example response (extract):

{
  "currentState": {
    "actions": [
      {
        "action": "ENABLE_ENCRYPTION_AT_REST",
        "status": "AVAILABLE",
        "blockedBy": null
      }
    ],
    "features": {
      "encryptionAtRest": {
        "enabled": false
      }
    }
  }
}

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:

  • PATCH changes only the features you name. Use it to change Encryption at Rest alone.
  • PUT replaces the whole target specification: every feature must be present in the body.

With PATCH, use the following API call and body:

{
  "checksum": "<checksum from your last read>",
  "targetSpec": {
    "features": {
      "encryptionAtRest": {
        "enabled": true
      }
    }
  }
}

With PUT, use the following API call:

The body has the same shape, with every feature of targetSpec.features filled in.

ParameterRequiredDescriptionExample
serviceNameYesService name of the Dedicated Server.ns1234567.ip-203-0-113.eu
checksum (body)YesChecksum returned by your last read of the server."a1b2c3..."
targetSpec.features.encryptionAtRest.enabled (body)Yestrue to enable, false to disable.true

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.

FieldWhat it tells you
targetSpec.features.encryptionAtRest.enabledThe state you requested.
currentState.features.encryptionAtRest.enabledThe state actually applied on the disks.
currentTasksThe operation in progress. The field is omitted when no operation is running.
resourceStatusUPDATING during the operation, then READY.

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.

Info

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.

HTTPError classCauseWhat to do
400Client::BadRequest::EncryptionAtRestNotEligibleThe server does not offer Encryption at Rest.Check the requirements and limitations.
400Client::BadRequest::EncryptionAtRestNotAvailableInRegionEncryption at Rest is not available in the server's region.No action is possible on this server for now.
400Client::BadRequest::ChecksumMissingThe body does not contain checksum.Read the server again and send its checksum.
400Client::BadRequest::TargetSpecEmptyThe PATCH body sets no feature.Fill in targetSpec.features.encryptionAtRest.
400Client::BadRequest::InvalidPayloadThe body is not valid.Check the body against the examples above.
404Client::NotFound::DedicatedServerNo server matches serviceName.Check the service name.
409Client::Conflict::ChecksumMismatchThe server changed since your last read.Read it again and send the new checksum.
409Client::Conflict::EncryptionAtRestAlreadyEnabledEncryption at Rest is already enabled.No action needed.
409Client::Conflict::EncryptionAtRestNotEnabledYou requested disabling, but Encryption at Rest is not enabled.No action needed.
409Client::Conflict::EncryptionAtRestNetworkPrerequisiteNotMetThe server has no bootable IP address, for example because OVHcloud Link Aggregation (OLA) is enabled.Restore the standard network configuration, then try again.
409Client::Conflict::OperationAlreadyRunningAnother operation is running on the server.Wait until it finishes, then try again.

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.

Esta página foi útil?