Creating KMS Keys

Here you'll find instructions for creating a cloud managed key for different cloud providers. The key is used as a part of the Vault auto-unseal process for users that choose to bundle Vault with their Garden Enterprise installation.

AWS Key Management Service

For auto-unsealing Vault on AWS, you'll need to first create a KMS key. Below you'll find a step-by-step guide for doing that.

Note that you may do things differently in your organization which is fine, as long as you have the following values at hand during the Garden Enterprise installation:

• The AWS KMS ID of the KMS Key you intend to use.

• The AWS Region where the key was created.

To provide authentication to AWS there are two options that will require different values. For option 1 you will need:

• The AWS Access Key ID and AWS Secret Access Key of an IAM user with access to the KMS key

Or alternatively, if you choose authentication option 2:

• The AWS Web Identity Session Role ARN for the vault service account in your EKS cluster

Please refer to the IAM Principal ARN section for more details on the authentication options.

IAM Principal ARN

For auto-unsealing Vault on AWS, you'll need a Principal ARN that refers to an entity with permissions to perform cryptographic operations on a symmetric KMS key.

Vault KMS AWS Authentication Options

There following options are available:

	Secrets involved	Principal ARN refers to	Requirements	Garden Cloud version
Option 1	AWS Access Key ID and AWS Secret Access Key	IAM User	-	All versions
Option 2	None	Web Identity Session Role	EKS with IRSA enabled	September 2022 and up

Option 2 simplifies operations by allowing to authenticate without the need to manage secrets, using IAM roles for service accounts (IRSA). With IRSA, The Garden Cloud Vault instance will authenticate to the AWS API and assume a Web Identity Session Role. This option only works in an AWS EKS cluster with IRSA enabled. If you fulfill the requirements, this is the recommended option.

In other cases you can fall back to option 1 (AWS Access Key ID and AWS Secret Access Key).

Option 1: AWS Access Key ID and Secret Access Key

An AWS Access Key ID and AWS Secret Access Key can be created on behalf of an IAM user. Please note these values, as you will need to enter these later during the Garden Cloud installation.

How you create and manage the IAM user depends on your organization.

Option 2: IAM roles for service accounts (IRSA)

For IRSA you need to create an IAM role that defines a trust relationship with your EKS cluster's OIDC provider. The Condition makes sure, that only the vault service account in the garden-enterprise namespace will be able to assume this role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "<OIDC Provider ARN>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "<OIDC Provider URL>:aud": "sts.amazonaws.com",
                    "<OIDC Provider URL>:sub": "system:serviceaccount:garden-enterprise:vault"
                }
            }
        }
    ]
}

Create an AWS KMS key via the AWS console

Go to the Key Management Service page in your AWS console and click Create key.

Make sure the key type is Symmetric:

Key type

Click Next.

Add a label

Add a label to your key so that you can identify it later:

Add label and description

The next steps pertain to defining administrative and/or usage permissions for the key. If and how you do this depends on your organization and is out of scope for this guide.

Keep the default key policy

Please keep the default KMS key policy. We will manage access in the next step.

Grant required permissions on the KMS key

Create a grant to allow the necessary operations on the KMS key for the Principal ARN (from the Principal ARN section above):

aws kms create-grant \
    --name garden-enterprise-kms-grant \
    --key-id <KMS Key ID> \
    --grantee-principal <Principal ARN> \
    --operations Decrypt Encrypt GenerateDataKey ReEncryptTo DescribeKey

And that’s it.

During the installation of Garden Enterprise you will be asked to provide the KMS configuration options mentioned above.

Google Cloud Key Management

For auto-unsealing Vault on GCP, you'll need to create a KMS key and configure the permissions of the instance groups service account to encrypt and decrypt that key. Below you'll find a step-by-step guide for doing that.

Note that you may do things differently in your organization which is fine, as long as you have the following values at hand during the Garden Enterprise installation:

• GCP Region

• GCP Project

• GCP Key Ring

• GCP Crypto Key

In order for your GKE cluster nodes to be able to access the API for fetching the KMS key for encryption/decryption you need to give the node pools service account the permissions to do so. You can either create a service account with the correct permissions in the IAM section or if you choose to use the Compute Engine default service account make sure to allow it full access to all Cloud APIs when creating the cluster.

Node pool service account

Create a GCP KMS key via the GCP console

Go to the Cryptographic Keys page in your GCP console and click Create key ring. Add a name for your new key ring and set the key ring location to the same location your GKE cluster uses.

Key ring

Next create a key in that key ring with the purpose symmetric encrypt/decrypt.

Key ring

Allow your service account to use the key for encryption/decryption

Select the created key and under the permissions tab choose Add a member. The member is the service account you have associated with your GKE clusters instance group. If your are not sure which one it is, go to Kubernetes Engine and check the node pool configuration of your cluster. Give your service account the role Cloud KMS CryptoKey Encrypter/Decrypter.

Key permissions

And that’s it.

During the installation of Garden Enterprise you will be asked to provide the key ring and crypto key name of the KMS key just created.

Azure Key Vault

For auto-unsealing Vault on Azure, you'll need to create an Azure Key Vault Instance and an app registration in Azure Active Directory. Then you'll need to add that service principle into the access policies of the key vault. Below you'll find a step-by-step guide for doing that.

Note that you may do things differently in your organization which is fine, as long as you have the following values at hand during the Garden Enterprise installation:

• Azure Application Client Id

• Azure Application Client Secret

• Azure Account Tenant Id

• Azure Vault Name

• Azure Key Name

Create an app registration

Go to the App Registrations page in Azure Active Directory and add a new registration.

App registration

After registering the application go to the API permissions tab and configure your apps access to Azure Vault Key.

App API permissions

Next navigate to Certificates & secrets and add a new client secret. You will need the Application Client Id and Application Client Secret for your Garden Enterprise installation.

Add an Azure Key Vault instance

Go to the Key Vaults page and create a new key vault. Enter your subscription, key vault name and region in the basics section and then navigate to the Access policy tab and choose the configuration template Key, Secret & Certificate Management. Then select the principal to be the app that you registered earlier.

Azure Vault access policy

Add a KMS key for auto-unsealing Garden Enterprise Vault

Once you have created your Azure Key Vault instance, add a key into it by navigating to the Keys tab in the Azure Key Vault instance and click Generate/Import. Your new key should be an RSA key, permit all operations and be enabled.

Key configuration

Once you have done that, take note of your Azure Vault Name and Azure Key Name and you should be all set.