---
title: "Encrypting a Block Storage volume with LUKS"
description: "Find out how to encrypt a Block Storage volume with LUKS, and how to use your own customer-managed key (CMK) stored in OKMS"
url: https://docs.ovhcloud.com/en/guides/public-cloud/compute/encrypting-a-block-storage-volume-with-luks
lang: en
lastUpdated: 2026-09-23
---
> For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/en/llms-full.txt.

# Encrypting a Block Storage volume with LUKS

## Objective

OVHcloud Block Storage volumes can be encrypted at rest using LUKS
. The encryption key — called a Service Key — is generated and stored in [OVHcloud Key Management Service (OKMS)](https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/overview.md)
.
By default, this Service Key is entirely generated and managed by OVHcloud: you simply order an encrypted (`-luks`) volume type and OVHcloud takes care of the rest. Optionally, you can instead use a **customer-managed key (CMK)**: a Service Key that you create and control yourself in your own OKMS domain, including its suspension and deletion.

**This guide first reminds how default (OVHcloud-managed) LUKS encryption works, then explains how to switch to a customer-managed key (CMK).**

:::warning
Encrypted (LUKS) volumes have a performance overhead of about 10% compared to equivalent non-encrypted volumes.
:::

## Default encryption (OVHcloud-managed key)

To encrypt a Block Storage volume with the default, OVHcloud-managed key, order the encrypted variant of any volume type (`classic-luks`, `high-speed-luks`, `high-speed-gen2-luks`) — from the Control Panel or with the tools described in the [How to create and configure an additional disk on an instance](https://docs.ovhcloud.com/en/guides/public-cloud/compute/create-and-configure-an-additional-disk-on-an-instance.md#the-different-types-of-volumes) guide. OVHcloud automatically generates and manages the Service Key in OKMS: there is no OKMS domain to create, no Service Key to manage, and no IAM policy to configure.

:::info
Once attached to your instance, an encrypted volume behaves like a standard volume — all encryption and unlocking are handled automatically by the OVHcloud infrastructure. See the [Migrating a Block Storage volume to an encrypted LUKS volume](https://docs.ovhcloud.com/en/guides/public-cloud/compute/migrating-non-encrypted-to-encrypted-volume.md) guide if you need to encrypt an existing, non-encrypted volume.
:::

:::warning
Do not modify or delete the automatically generated key linked to a `-luks` volume. Doing so would make the data on that volume, and all its snapshots, permanently unrecoverable.
:::

The rest of this guide covers the customer-managed key (CMK) alternative.

## Using a customer-managed key (CMK)

Most steps below are documented in 2 ways:

- via the **OVHcloud Control Panel**, available today for the OKMS and IAM operations;
- via the **OVHcloud API** or the **OpenStack CLI**, currently the only ways to create the encrypted Block Storage volume itself. Control Panel support for volume creation with a CMK is coming soon.

## Requirements

These requirements apply only to the customer-managed key (CMK) workflow below.

- An active OVHcloud account with sufficient rights to manage IAM, OKMS, and Block Storage.
- API access with valid credentials — a Bearer token (OAuth2 via an IAM service account) or the classic application key / signature authentication. See the [First Steps with the OVHcloud APIs](https://docs.ovhcloud.com/en/guides/manage-and-operate/api/first-steps.md) guide.
- Optionally, the OpenStack CLI installed and configured for the target region, as an alternative to the OVHcloud API for creating the volume. See the [Preparing an environment for using the OpenStack API](https://docs.ovhcloud.com/en/guides/public-cloud/cross-functional/compute-prepare-openstack-api-environment.md) guide.
- Appropriate IAM permissions to create policies and assign them to OVHcloud NICs — specifically the `account:apiovh:iam/policy/create` action.

***

### OVHcloud Control Panel Access


**Policies:**

- **Direct link:** <ManagerLink to="/#/iam/policies/myPolicies">Policies</ManagerLink>
- **Navigation path:** <code className="action">Identity, Security & Operations</code> > <code className="action">Policies</code>



**Key Management Service:**

- **Direct link:** <ManagerLink to="/#/okms/key-management-service">Key Management Service</ManagerLink>
- **Navigation path:** <code className="action">Identity, Security & Operations</code> > <code className="action">Key Management Service</code> > Select your OKMS domain


***

## Instructions

Each step below presents the available interfaces as tabs: OVHcloud Control Panel, OVHcloud API, or OpenStack CLI.

:::info
For API calls, the base URL is `https://api.eu.ovhcloud.com` in Europe and `https://api.ca.ovhcloud.com` in Canada, each serving both the `/v1/*` and `/v2/*` endpoints.

:::

### Step 1: Create an OKMS domain [](#)
An OKMS domain is a logical namespace inside OKMS that holds your Service Keys. Each domain is tied to a specific region.

An OKMS domain is ordered as a service from the OVHcloud Control Panel; the OVHcloud API is then used to retrieve its ID.


**OVHcloud Control Panel**

To order an OKMS domain, follow the "Ordering your KMS" section of the [Getting started with OVHcloud Key Management Service (KMS)](https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/quick-start.md#ordering-your-kms) guide.


**OVHcloud API**

Once you have ordered a domain, list your domains and retrieve their IDs via the API:
**List all your OKMS domains:**

🇪🇺EU▾

[GET/okms/resource](https://api.eu.ovhcloud.com/console/?section=/okms&branch=v2#get-/okms/resource)

**Get details of a specific OKMS domain:**

🇪🇺EU▾

[GET/okms/resource/{okmsId}](https://api.eu.ovhcloud.com/console/?section=/okms&branch=v2#get-/okms/resource/-okmsId-)

| Variable | Description               |
| -------- | ------------------------- |
| `okmsId` | UUID of your OKMS domain. |


:::info
Note your **OKMS domain ID** (`okms_domain_id` / `domainId`). You will need it when creating the LUKS volume in [Step 4](#step4).
:::

### Step 2: Create a Service Key [](#)
A Service Key is a cryptographic key stored inside your OKMS domain. The Block Storage service uses it to generate and protect the data encryption keys (DEKs) that encrypt your volumes.


**OVHcloud Control Panel**

To create the Service Key, follow the "Create an encryption key" section of the [Getting started with OVHcloud Key Management Service (KMS)](https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/quick-start.md#create-an-encryption-key) guide, and set the following parameters:
| Parameter                    | Required value                   | Notes                                                               |
| ---------------------------- | -------------------------------- | ------------------------------------------------------------------- |
| Service Key type             | AES                              | Symmetric encryption algorithm required for LUKS volume encryption. |
| Service Key size (Algorithm) | 256 bits                         | 256-bit key length, for AES-256 encryption strength.                |
| Service Key usage            | Wrap / Unwrap, Encrypt / Decrypt | These operations are mandatory.                                     |
Once created, note the **Service Key ID** (`okms_servicekey_id` / `serviceKeyId`).


**OVHcloud API**

Create the Service Key with the following API call:

🇪🇺EU▾

[POST/okms/resource/{okmsId}/serviceKey](https://api.eu.ovhcloud.com/console/?section=/okms&branch=v2#post-/okms/resource/-okmsId-/serviceKey)

| Variable | Description                        |
| -------- | ---------------------------------- |
| `okmsId` | UUID of your OKMS domain (Step 1). |
Payload:
```json
{
  "name": "cmk-luks-volumes",
  "type": "oct",
  "size": 256,
  "operations": ["encrypt", "decrypt", "wrapKey", "unwrapKey"]
}
```
| Field        | Value                                        | Notes                                                                                 |
| ------------ | -------------------------------------------- | ------------------------------------------------------------------------------------- |
| `name`       | free text                                    | A descriptive key name.                                                               |
| `type`       | `oct`                                        | Symmetric key (AES). The API uses the JWK naming: `oct` = octet sequence / symmetric. |
| `size`       | `256`                                        | Key size in bits.                                                                     |
| `operations` | `encrypt`, `decrypt`, `wrapKey`, `unwrapKey` | All 4 are required for LUKS volume encryption.                                        |
The response contains the key `id` — this is your Service Key ID.


:::info
**Why wrap / unwrap?** The Block Storage service uses the Service Key to wrap (encrypt) the generated data encryption key (DEK) before storing it, and to unwrap (decrypt) it when the volume needs to be accessed. The Service Key itself never leaves OKMS.
:::

:::info
**BYOK.** Instead of letting OKMS generate the Service Key, you can import your own key material using [Bring Your Own Key (BYOK)](https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/import-export-keys-byok.md), which wraps the key with an RSA transport key pair so it never travels in plaintext.
:::

### Step 3: Delegate access via an IAM policy

To allow OVHcloud's OpenStack services to create and use LUKS volumes with your key, you must grant specific IAM permissions to the OVHcloud NIC associated with the Block Storage service in your region.

#### 3.1 Identify the OVHcloud NIC for your region

Each OVHcloud region has a dedicated internal NIC that the Block Storage service uses to interact with OKMS:

| Region                                          | OVHcloud NIC    |
| ----------------------------------------------- | --------------- |
| `GRA1`, `GRA3`, `GRA5`, `GRA7`, `GRA9`, `GRA11` | `vt202366-ovh`  |
| `BHS1`, `BHS3`, `BHS5`                          | `rh149494-ovh`  |
| `SBG5`, `SBG7`                                  | `yq2822-ovh`    |
| `EU-WEST-PAR`                                   | `dy230283-ovh`  |
| `EU-SOUTH-MIL`                                  | `xz3473-ovh`    |
| `DE1`                                           | `qy10886-ovh`   |
| `UK1`                                           | `gz25568-ovh`   |
| `WAW1`                                          | `xe2946-ovh`    |
| `RBX-A`                                         | `xz3500-ovh`    |
| `SGP1`                                          | `sc1243248-ovh` |
| `SYD1`                                          | `oy31561-ovh`   |
| `AP-SOUTHEAST-SYD-2`                            | `td444999-ovh`  |
| `AP-SOUTH-MUM-1`                                | `pu54673-ovh`   |

:::warning
If your region is not listed here, contact [OVHcloud support](https://www.ovhcloud.com/en-gb/support-levels/) to obtain the correct NIC.
:::

#### 3.2 Create the IAM policy


**OVHcloud Control Panel**

Create a new IAM policy in the Control Panel, as described in the [How to use IAM policies using the OVHcloud Control Panel](https://docs.ovhcloud.com/en/guides/account-and-service-management/account-information/iam-policy-ui.md) guide, and configure it with the following values:
| Field         | Value                                                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Identities    | Under **Other OVHcloud customer accounts**, click <code className="action">Add an account</code> and enter the NIC for your region (see 3.1). |
| Product types | <code className="action">Key Management Service (OKMS) / Service Keys</code>                                                                  |
| Resources     | Select the specific Service Key created in Step 2.                                                                                            |
| Actions       | See [3.3 Actions to authorize](#actions33) below.                                                                                             |


**OVHcloud API**

First, retrieve the **IAM URN** of your Service Key (returned in the `urn` field of the response's `iam` block):

🇪🇺EU▾

[GET/okms/resource/{okmsId}/serviceKey/{keyId}](https://api.eu.ovhcloud.com/console/?section=/okms&branch=v2#get-/okms/resource/-okmsId-/serviceKey/-keyId-)

| Variable | Description                        |
| -------- | ---------------------------------- |
| `okmsId` | UUID of your OKMS domain (Step 1). |
| `keyId`  | UUID of your Service Key (Step 2). |
Then create the policy:

🇪🇺EU▾

[POST/iam/policy](https://api.eu.ovhcloud.com/console/?section=/iam&branch=v2#post-/iam/policy)

Payload:
```json
{
  "name": "allow-blockstorage-cmk-luks",
  "description": "Allow the regional Block Storage NIC to use my Service Key for LUKS volumes",
  "identities": [
    "urn:v1:eu:identity:account:{blockStorageNic}"
  ],
  "resources": [
    { "urn": "{serviceKeyIamUrn}" }
  ],
  "permissions": {
    "allow": [
      { "action": "okms:apikms:serviceKey/dataKey/create" },
      { "action": "okms:apikms:serviceKey/dataKey/decrypt" }
    ]
  }
}
```
| Variable / field    | Value               | Notes                                                                       |
| ------------------- | ------------------- | --------------------------------------------------------------------------- |
| `blockStorageNic`   | e.g. `dy230283-ovh` | The regional OVHcloud NIC identified in 3.1.                                |
| `serviceKeyIamUrn`  | Service Key IAM URN | The `iam.urn` value retrieved above — scopes the policy to that single key. |
| `permissions.allow` | see 3.3             | The 2 mandatory actions.                                                    |


#### 3.3 Actions to authorize [](#)
Under `Key Management Service (OKMS) / Service Keys
`, in the `OPERATE
` category:
| Action                                   | Purpose                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `okms:apikms:serviceKey/dataKey/create`  | Allows Block Storage to generate a new data encryption key (DEK).      |
| `okms:apikms:serviceKey/dataKey/decrypt` | Allows Block Storage to decrypt the data key to access encrypted data. |

### Step 4: Create the LUKS volume [](#)
:::warning
Volume creation with a CMK is currently available **via API only** (OVHcloud API or OpenStack CLI). Control Panel support is coming soon.
:::


**OVHcloud API**

Create the LUKS volume with the following API call:

🇪🇺EU▾

[POST/cloud/project/{serviceName}/region/{regionName}/volume](https://api.eu.ovhcloud.com/console/?section=/cloud&branch=v1#post-/cloud/project/-serviceName-/region/-regionName-/volume)

| Variable      | Description                        |
| ------------- | ---------------------------------- |
| `serviceName` | Your Public Cloud project ID.      |
| `regionName`  | Target region, e.g. `EU-WEST-PAR`. |
Payload:
```json
{
  "name": "my-encrypted-volume",
  "description": "CMK LUKS encrypted volume",
  "size": 50,
  "type": "high-speed-gen2-luks",
  "availabilityZone": "eu-west-par-a",
  "encryption": {
    "encrypted": true,
    "kms": {
      "domainId": "{okmsDomainId}",
      "serviceKeyId": "{serviceKeyId}"
    }
  }
}
```
| Field                         | Example value          | Description                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`                        | `50`                   | Size of the volume in gigabytes.                                                                                                                                                                                                                                                                                                                                          |
| `type`                        | `high-speed-gen2-luks` | LUKS-enabled volume type (`classic-luks`, `high-speed-luks`, `high-speed-gen2-luks`). `classic-luks` is not available in 3-AZ regions — use `high-speed-gen2-luks` there. See the [volume types overview](https://docs.ovhcloud.com/en/guides/public-cloud/compute/create-and-configure-an-additional-disk-on-an-instance.md#the-different-types-of-volumes) for details. |
| `availabilityZone`            | `eu-west-par-a`        | Target availability zone, used in 3-AZ regions.                                                                                                                                                                                                                                                                                                                           |
| `encryption.kms.domainId`     | `{okmsDomainId}`       | UUID of your OKMS domain (Step 1).                                                                                                                                                                                                                                                                                                                                        |
| `encryption.kms.serviceKeyId` | `{serviceKeyId}`       | UUID of your Service Key (Step 2).                                                                                                                                                                                                                                                                                                                                        |


**OpenStack CLI**

```bash
openstack volume create \
  --size 50 \
  --availability-zone eu-west-par-a \
  --property okms_domain_id={okmsDomainId} \
  --property okms_servicekey_id={serviceKeyId} \
  --type high-speed-gen2-luks \
  my-encrypted-volume
```
| Parameter or argument           | Example value          | Description                                                                            |
| ------------------------------- | ---------------------- | -------------------------------------------------------------------------------------- |
| `--size`                        | `50`                   | Size of the volume in gigabytes.                                                       |
| `--availability-zone`           | `eu-west-par-a`        | Target availability zone, used in 3-AZ regions.                                        |
| `--property okms_domain_id`     | `{okmsDomainId}`       | UUID of your OKMS domain.                                                              |
| `--property okms_servicekey_id` | `{serviceKeyId}`       | UUID of your Service Key within the OKMS domain.                                       |
| `--type`                        | `high-speed-gen2-luks` | Volume type enabling LUKS encryption. `classic-luks` is not available in 3-AZ regions. |
| `my-encrypted-volume`           | —                      | A descriptive name for your new volume.                                                |


### Step 5: Use the volume

Once created, a CMK LUKS encrypted volume behaves like a standard OVHcloud Block Storage volume: you [attach](https://docs.ovhcloud.com/en/guides/public-cloud/compute/create-and-configure-an-additional-disk-on-an-instance.md#attaching-a-new-volume) and [detach](https://docs.ovhcloud.com/en/guides/public-cloud/compute/create-and-configure-an-additional-disk-on-an-instance.md#detach-a-volume) it the same way. Deleting the volume does not delete your Service Key.

:::warning
**Key availability.** If your Service Key is deleted in OKMS, a volume that is currently attached keeps working — the key is only needed again once the volume is detached, or once the instance is migrated (whether by OVHcloud or by you), at which point the volume becomes permanently inaccessible. Suspending a key, on the other hand, is reversible: unsuspending it restores access with no data loss. Always ensure your key lifecycle management aligns with your data access requirements.
:::

## Limitations

Converting a volume to an image is not supported for LUKS volumes, whether the encrypted version uses a CMK or the default OVHcloud-managed key. This restriction applies regardless of the tool used — Control Panel, OVHcloud API, OpenStack CLI, or Terraform.

## Summary

| # | Step               | Control Panel           | API                                                                                |
| - | ------------------ | ----------------------- | ---------------------------------------------------------------------------------- |
| 1 | Create OKMS domain | Order via Control Panel | List/read via `GET /v2/okms/resource`                                              |
| 2 | Create Service Key | ✅                       | `POST /v2/okms/resource/{okmsId}/serviceKey`                                       |
| 3 | Create IAM policy  | ✅                       | `POST /v2/iam/policy`                                                              |
| 4 | Create LUKS volume | Coming soon             | `POST /v1/cloud/project/{serviceName}/region/{regionName}/volume` or OpenStack CLI |
| 5 | Use the volume     | ✅                       | Standard volume operations                                                         |

## Go further

[How to create and configure an additional disk on an instance](https://docs.ovhcloud.com/en/guides/public-cloud/compute/create-and-configure-an-additional-disk-on-an-instance.md)

[Migrating a Block Storage volume to an encrypted LUKS volume](https://docs.ovhcloud.com/en/guides/public-cloud/compute/migrating-non-encrypted-to-encrypted-volume.md)

[Getting started with OVHcloud Key Management Service (KMS)](https://docs.ovhcloud.com/en/guides/manage-and-operate/kms/quick-start.md)

[How to use IAM policies using the OVHcloud Control Panel](https://docs.ovhcloud.com/en/guides/account-and-service-management/account-information/iam-policy-ui.md)

Join our [community of users](https://community.ovhcloud.com/).