Skip to content

Use Your Own Encryption Key (CMK)

Overview

Your Nautobot Cloud database (Amazon RDS) can be encrypted with a customer managed key (CMK): an AWS KMS key that you own and control, instead of a key managed by Network to Code. The key stays in your AWS account; you grant your dedicated Nautobot Cloud AWS account permission to use it.

The key must be in place before Network to Code deploys your environment. RDS encryption is set when the database is created and can't be switched to a different key afterward.

  1. Network to Code sends you the AWS account ID of your new Nautobot Cloud account and the AWS region it runs in.
  2. You create a KMS key in that region and grant the Nautobot Cloud account access (this guide).
  3. You send the key ARN to Network to Code through a support ticket.
  4. Network to Code verifies that the Nautobot Cloud account can use the key, then deploys your environment.

To request this option, contact your Network to Code account team or open a ticket through the support portal.

OPEN A TICKET

What your key encrypts

Your key encrypts the Nautobot Cloud database: its storage, its automated backups, and its RDS snapshots.

Everything else in your environment stays encrypted at rest with KMS keys that Network to Code manages. That includes file storage, object storage, and Snapshots you create in the Cloud Console, which are stored separately from the database.

Key requirements

The key must meet every requirement below, or the database can't be created with it.

Setting Required value
Key type Symmetric
Key usage Encrypt and decrypt
Key spec SYMMETRIC_DEFAULT
Region The same region as your Nautobot Cloud environment (provided by Network to Code)
State Enabled
Key material origin AWS KMS (default)
Key policy Includes the Nautobot Cloud statement in Key policy statement below

A single-Region key is fine. A multi-Region key also works if it has a replica in your environment's region; send the replica's ARN.

Option A: Create the key in the AWS console

Use this if you manage keys through the console. You need permission to create KMS keys and edit key policies in your account. AWS's own walkthrough is Create a symmetric encryption KMS key.

  1. Sign in to the AWS console and switch to your environment's region (top-right region selector).
  2. Open Key Management Service (KMS), then Customer managed keys, then Create key.
  3. Configure key:
    • Key type: Symmetric
    • Key usage: Encrypt and decrypt
    • Under Advanced options, leave Key material origin as KMS and Regionality as Single-Region key.
  4. Add labels: give it an alias such as nautobot-cloud-rds and a description. Add any tags your organization requires.
  5. Define key administrative permissions: choose the people or roles in your organization who manage the key. Leave this to your normal practice.
  6. Define key usage permissions: select any of your own users or roles that should use the key, if any. Do not add the Nautobot Cloud account under Other AWS accounts; the next step adds the exact permissions it needs instead.
  7. Edit key policy: on the review page, choose Edit on the key policy. Add the statement from Key policy statement below as a new entry in the Statement list, replacing <NAUTOBOT_CLOUD_ACCOUNT_ID> with the account ID Network to Code sent you. Make sure the JSON stays valid: separate statements with a comma.
  8. Choose Finish.
  9. Open the new key and copy its ARN (it looks like arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab). Send this ARN, not the alias.

To use an existing key instead, open it, choose Key policy, then Edit, add the same statement, and save.

Option B: Create the key with the AWS CLI

Use this if you script your infrastructure. Replace the placeholders first:

  • <YOUR_ACCOUNT_ID>: your AWS account ID (the one that will own the key)
  • <NAUTOBOT_CLOUD_ACCOUNT_ID>: the account ID Network to Code sent you
  • <REGION>: your environment's region

Then run these steps:

  1. Save this as key-policy.json. The first statement keeps your account in control of the key; without it you can lock yourself out. The second is the Nautobot Cloud statement.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EnableOwnerAccountPermissions",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<YOUR_ACCOUNT_ID>:root" },
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "AllowNautobotCloudUseOfTheKey",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<NAUTOBOT_CLOUD_ACCOUNT_ID>:root" },
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey",
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
      ],
      "Resource": "*"
    }
  ]
}

  2. Create the key and print its ARN:

    aws kms create-key \
  --region <REGION> \
  --description "Nautobot Cloud RDS encryption" \
  --key-spec SYMMETRIC_DEFAULT \
  --key-usage ENCRYPT_DECRYPT \
  --policy file://key-policy.json \
  --query KeyMetadata.Arn --output text

  3. Optionally give it an alias and turn on yearly automatic rotation (rotation needs no action from Network to Code):

    aws kms create-alias --region <REGION> \
  --alias-name alias/nautobot-cloud-rds --target-key-id <KEY_ARN>

aws kms enable-key-rotation --region <REGION> --key-id <KEY_ARN>

If your organization already defines key administrators and users in the policy, keep those statements and add only the second statement above.

For an existing key, fetch its policy, add the Nautobot Cloud statement to the Statement list, then apply it:

aws kms get-key-policy --region <REGION> --key-id <KEY_ARN> \
  --policy-name default --query Policy --output text > key-policy.json

# edit key-policy.json to add the Nautobot Cloud statement

aws kms put-key-policy --region <REGION> --key-id <KEY_ARN> \
  --policy-name default --policy file://key-policy.json

Key policy statement

Add this statement to the key policy, with <NAUTOBOT_CLOUD_ACCOUNT_ID> replaced by the account ID Network to Code sent you. It grants the Nautobot Cloud account only the permissions RDS needs to encrypt your database with the key; it doesn't allow that account to manage, disable, or delete the key.

{
  "Sid": "AllowNautobotCloudUseOfTheKey",
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::<NAUTOBOT_CLOUD_ACCOUNT_ID>:root" },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:DescribeKey",
    "kms:CreateGrant",
    "kms:ListGrants",
    "kms:RevokeGrant"
  ],
  "Resource": "*"
}
Permission Why it's needed
kms:Encrypt, kms:Decrypt, kms:ReEncrypt* Encrypt and read the database storage, snapshots, and backups
kms:GenerateDataKey* Create the data keys RDS uses to encrypt storage
kms:DescribeKey Confirm the key exists and is a valid symmetric key
kms:CreateGrant, kms:ListGrants, kms:RevokeGrant Let RDS hold and manage the grants it uses to access the key while the database runs

The root principal refers to the Nautobot Cloud account as a whole, not a root user. Within that account, access is limited to the Nautobot Cloud platform's own roles. See AWS's Allowing users in other accounts to use a KMS key for how cross-account key policies work.

Send the key ARN

Send the key's full ARN through a support ticket, in the form arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KEY_ID>. An alias ARN (...:alias/...) won't work.

Before deploying, Network to Code verifies from the Nautobot Cloud account that it can describe the key, encrypt and decrypt a test value, and create (then immediately remove) a test grant. Nothing is stored with your key during this check.

If any check fails, the support team tells you which permission was denied so you can adjust the key policy. Once all checks pass, Network to Code deploys your environment and your database is created encrypted with your key.

Important notes

You keep full control of the key, and your environment depends on it staying usable.

  • Don't disable the key, schedule it for deletion, or remove the Nautobot Cloud statement. The database becomes unreachable, and a deleted key makes the data and backups permanently unrecoverable. Open a support ticket before any change to the key or its policy.
  • Automatic rotation is fine. AWS keeps older key material available, so rotation needs no action from you or Network to Code.
  • Don't add conditions to the Nautobot Cloud statement (such as kms:ViaService or kms:GrantIsForAWSResource) without telling the support team first. They can block the pre-deployment check even when RDS itself would work.
  • Costs: standard AWS KMS charges for the key and its requests are billed to your account.

Troubleshooting

If the pre-deployment check fails, the support team reports the error returned by AWS.

Reported error Usual cause Fix
AccessDeniedException on any call Nautobot Cloud statement missing, or wrong account ID Add the statement with the account ID Network to Code sent you
NotFoundException Key is in a different region, or the ARN has a typo Create the key in your environment's region; resend the ARN
Key state is not Enabled Key disabled or pending deletion Enable the key or cancel the deletion
Key isn't symmetric Key created as asymmetric or HMAC Create a new symmetric encrypt-and-decrypt key

AWS documentation