Mount secrets in Amazon EKS - AWS Secrets Manager

The ASCP retrieves the pod identity and exchanges it for the IAM role. ASCP assumes the IAM role of the pod, which gives it access to the secrets you authorized. Other containers can't access the secrets unless you also associate them with the IAM role.

For information about creating policies, see the section called “Attach a permissions policy to an identity” (p. 16).

For a tutorial about how to use the ASCP, see the section called “Tutorial” (p. 79).

Step 2: Mount secrets in Amazon EKS

To show secrets in Amazon EKS as though they are ﬁles on the ﬁlesystem, you create a

SecretProviderClass YAML ﬁle that contains information about your secrets and how to display them in the Amazon EKS pod.

The SecretProviderClass must be in the same namespace as the Amazon EKS pod it references.

If Amazon EKS does not have internet access, for the provider to access Secrets Manager, you need to set up a VPC endpoint (p. 101).

For a tutorial about how to use the ASCP, see the section called “Tutorial” (p. 79).

SecretProviderClass

The SecretProviderClass YAML has the following format:

apiVersion: secrets-store.csi.x-k8s.io/v1alpha1 kind: SecretProviderClass

metadata:

name: <NAME>

spec:

provider: aws parameters:

parameters

Contains the details of the mount request.

objects

A string containing a YAML declaration of the secrets to be mounted. We recommend using a YAML multi-line string or pipe (|) character, as shown in the section called “Example” (p. 78).

objectName

The name or full ARN of the secret. If you use the ARN, you can omit objectType.

This becomes the ﬁle name of the secret in the Amazon EKS pod unless you specify objectAlias.

jmesPath

(Optional) A map of the keys in the secret to the ﬁles to be mounted in Amazon EKS. To use this ﬁeld, your secret value must be in JSON format. If you use this ﬁeld, you must include the subﬁelds path and objectAlias.

path

A key from a key/value pair in the JSON of the secret value.

objectAlias

The ﬁle name to be mounted in the Amazon EKS pod.

SecretProviderClass

objectType

Required if you don't use a Secrets Manager ARN for objectName. Can be either secretsmanager or ssmparameter.

objectAlias

(Optional) The ﬁle name of the secret in the Amazon EKS pod. If you don't specify this ﬁeld, the objectName appears as the ﬁle name.

objectVersion

(Optional) The version ID of the secret. We recommend you don't use this ﬁeld because you must update it every time you update the secret. By default the most recent version is used.

objectVersionLabel

(Optional) The alias for the version. The default is the most recent version AWSCURRENT.

For more information, see the section called “Version” (p. 11).

region

(Optional) The AWS Region of the secret. If you don't use this ﬁeld, the ASCP looks up the Region from the annotation on the node. This lookup adds overhead to mount requests, so we recommend that you provide the Region for clusters that use large numbers of pods.

pathTranslation

(Optional) A single substitution character to use if the ﬁle name (either objectName or

objectAlias) contains the path separator character, such as slash (/) on Linux. If a secret contains the path separator, the ASCP will not be able to create a mounted ﬁle with that name. Instead, you can replace the path separator character with a diﬀerent character by entering it in this ﬁeld. If you don't use this ﬁeld, the default is underscore (_), so for example, My/Path/Secret mounts as My_Path_Secret.

To prevent character substitution, enter the string False.

Example

The following example shows a SecretProviderClass that mounts six ﬁles in Amazon EKS:

1. A secret speciﬁed by full ARN.

2. The username key/value pair from the same secret.

3. The password key/value pair from the same secret.

4. A secret speciﬁed by full ARN.

5. A secret speciﬁed by name.

6. A speciﬁc version of a secret.

apiVersion: secrets-store.csi.x-k8s.io/v1alpha1 kind: SecretProviderClass

metadata:

name: aws-secrets spec:

provider: aws parameters:

objects: |

- objectName: "arn:aws:secretsmanager:us-east-2:

[111122223333]:secret:MySecret-00AACC"

jmesPath:

- path: username

objectAlias: dbusername

Tutorial

- path: password

objectAlias: dbpassword

- objectName: "arn:aws:secretsmanager:us-east-2:

[111122223333]:secret:MySecret2-00AABB"

- objectName: "MySecret3"

objectType: "secretsmanager"

- objectName: "MySecret4"

objectType: "secretsmanager"

objectVersionLabel: "AWSCURRENT"

Tutorial: Create and mount a secret in an Amazon EKS pod

In this tutorial, you create an example secret in Secrets Manager, and then you mount the secret in an Amazon EKS pod and deploy it.

Before you begin, install the ASCP: the section called “Install the ASCP” (p. 76).

To create and mount a secret

1. Set the AWS Region and the name of your cluster as shell variables so you can use them in bash commands. For <REGION>, enter the AWS Region where your Amazon EKS cluster runs. For

<CLUSTERNAME>, enter the name of your cluster.

REGION=<REGION>

CLUSTERNAME=<CLUSTERNAME>

2. Create a test secret. For more information, see the section called “Create a secret” (p. 38).

aws --region "$REGION" secretsmanager create-secret --name MySecret --secret-string '{"username":"lijuan", "password":"hunter2"}'

3. Create a resource policy for the pod that limits its access to the secret you created in the previous step. For <SECRETARN>, use the ARN of the secret. Save the policy ARN in a shell variable.

POLICY_ARN=$(aws --region "$REGION" --query Policy.Arn --output text iam create-policy --policy-name nginx-deployment-policy --policy-document '{

"Version": "2012-10-17", "Statement": [ {

"Effect": "Allow",

"Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], "Resource": ["<SECRETARN>"]

} ] }')

4. Create an IAM OIDC provider for the cluster if you don't already have one. For more information, see Create an IAM OIDC provider for your cluster.

eksctl utils associate-iam-oidc-provider region="$REGION" cluster="$CLUSTERNAME" --approve # Only run this once

5. Create the service account the pod uses and associate the resource policy you created in step 3 with that service account. For this tutorial, for the service account name, you use nginx-deployment-sa.

For more information, see Create an IAM role for a service account.

eksctl create iamserviceaccount --name nginx-deployment-sa --region="$REGION" --cluster "$CLUSTERNAME" --attach-policy-arn "$POLICY_ARN" --approve --override-existing-serviceaccounts

Tutorial

6. Create the SecretProviderClass to specify which secret to mount in the pod. The following command uses ExampleSecretProviderClass.yaml in the ASCP GitHub repo examples directory to mount the secret you created in step 1. For information about creating your own SecretProviderClass, see the section called “SecretProviderClass” (p. 77).

kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/examples/ExampleSecretProviderClass.yaml

7. Deploy your pod. The following command uses ExampleDeployment.yaml in the ASCP GitHub repo examples directory to mount the secret in /mnt/secrets-store in the pod.

kubectl apply -f https://raw.githubusercontent.com/aws/secrets-store-csi-driver-provider-aws/main/examples/ExampleDeployment.yaml

8. To verify the secret has been mounted properly, use the following command and conﬁrm that your secret value appears.

kubectl exec -it $(kubectl get pods | awk '/nginx-deployment/{print $1}' | head -1) cat /mnt/secrets-store/MySecret; echo

The secret value appears.

{"username":"lijuan", "password":"hunter2"}

Troubleshoot

You can view most errors by describing the pod deployment.

To see error messages for your container

1. Get a list of pod names with the following command. If you aren't using the default namespace, use -n <NAMESPACE>.

kubectl get pods

2. To describe the pod, in the following command, for <PODID> use the pod ID from the pods you found in the previous step. If you aren't using the default namespace, use -n <NAMESPACE>.

kubectl describe pod/<PODID>

To see errors for the ASCP

• To ﬁnd more information in the provider logs, in the following command, for <PODID> use the ID of the csi-secrets-store-provider-aws pod.

kubectl -n kube-system get pods

kubectl -n kube-system logs pod/<PODID>

Rotation strategies

Rotate AWS Secrets Manager secrets

Rotation is the process of periodically updating a secret. When you rotate a secret, you update the credentials in both the secret and the database or service. In Secrets Manager, you can set up automatic rotation for your secrets. Applications that retrieve the secret from Secrets Manager automatically get the new credentials after rotation.

To turn on automatic rotation, you need administrator permissions. See the section called “Secrets Manager administrator permissions” (p. 15).

Topics

• Rotation strategies (p. 81)

• Automatically rotate an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret (p. 83)

• Automatically rotate another type of secret (p. 84)

• Schedule expressions in Secrets Manager rotation (p. 86)

• Rotate a secret immediately (p. 88)

• How rotation works (p. 88)

• Network access for the rotation function (p. 89)

• Permissions for rotation (p. 90)

• Customize a Lambda rotation function for Secrets Manager (p. 93)

• Secrets Manager rotation function templates (p. 94)

Rotation strategies

There are two rotation strategies oﬀered by Secrets Manager:

• the section called “Single user” (p. 81)

• the section called “Alternating users” (p. 82)

Single user rotation strategy

The single user strategy updates credentials for one user in one secret.

This is the simplest rotation strategy, and it is appropriate for most use cases. You can use single-user rotation for:

• Accessing databases. Database connections are not dropped when a secret rotates, and new connections after rotation use the new credentials.

• Accessing services that allow the user to create one user account, for example with email address as the user name. The service typically allows the user to change the password as often as required, but the user can't create additional users or change their user name.

• Users created as necessary, called ad-hoc users.

Alternating users

• Users who enter their password interactively instead of having an application programmatically retrieve it from Secrets Manager. This type of user does not expect to have to change their user name as well as password.

While this type of rotation is happening, there is a short period of time between when the password in the database changes and when the corresponding secret updates. In this time, there is a low risk of the database denying calls that use the rotated credentials. You can mitigate this risk with an appropriate retry strategy.

To use this strategy, the user in your secret must have permission to update their password.

To use the single user rotation strategy

1. Create a secret with the database or service credentials.

2. Turn on automatic rotation for your secret, and for Select which secret will be used to perform the rotation, choose Use this secret / Single user rotation.

Alternating users rotation strategy

The alternating users strategy updates credentials for two users in one secret. You create the ﬁrst user, and rotation clones it to create the second.

Each subsequent version of a secret updates the other user. For example, if the ﬁrst version has user1/

password1, then the second version has user2/password2. The third version has user1/password3, and the fourth version has user2/password4. You have two sets of valid credentials at any given time:

both the current and previous credentials are valid.

Applications continue to use the existing version of the credentials while rotation creates the new version. Once the new version is ready, rotation switches the staging labels so that applications use the new version.

A separate secret contains credentials for an administrator or superuser who can create the second user and update both users' credentials.

This strategy is appropriate for:

• Applications and databases with permission models where one role owns the database tables and a second role for the application has permission to access the tables.

• Applications that require high availability. There is less chance of applications getting a deny during this type of rotation than single user rotation.

If the database or service is hosted on a server farm where the password change takes time to propagate to all member servers, there is a risk of the database denying calls that use the rotated credentials. You can mitigate this risk with an appropriate retry strategy.

To use this strategy, you need a separate secret with credentials for an administrator or superuser who has permissions to create a user and change password on both users. The ﬁrst rotation clones this user to create the alternate user to ensure that both users have the same permissions.

To use the alternating users strategy

1. Create a user with elevated credentials for your database or service. This user must be able to create new users and change their credentials.

2. Create a secret for the elevated user's credentials.

Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret 3. Create a user who will access your database or service.

4. Create a secret for the user's credentials.

5. Turn on automatic rotation for your user's secret, and for Select which secret will be used to perform the rotation, choose Use a secret I previously stored / Multi-user rotation and then choose the elevated user secret.

Automatically rotate an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret

Secrets Manager provides complete rotation templates for Amazon RDS, Amazon DocumentDB, and Amazon Redshift secrets. For other types of secrets, see the section called “Other type of secret” (p. 84).

Rotation functions for Amazon RDS (except Oracle) and Amazon DocumentDB automatically use Secure Socket Layer (SSL) or Transport Layer Security (TLS) to connect to your database, if it is available.

Otherwise they use an unencrypted connection.

Note

If you set up automatic secret rotation before December 20, 2021, your rotation function might be based on an older template that did not support SSL/TLS. See Determine when your rotation function was created (p. 135). If it was created before December 20, 2021, to support connections that use SSL/TLS, you need to recreate your rotation function (p. 83).

Edit your secret, and then choose Edit rotation. In the dialog box, choose Create a rotation function to recreate your rotation function. If you made customizations (p. 93) to your previous rotation function, you must redo them in the new rotation function.

Another way to automatically rotate a secret is to use AWS CloudFormation to create the secret, and include AWS::SecretsManager::RotationSchedule. See Automate secret creation in AWS CloudFormation.

Before you begin, you need the following:

• A user with credentials to Amazon RDS, Amazon DocumentDB, or Amazon Redshift.

• A rotation strategy. See the section called “Rotation strategies” (p. 81).

• If you use the the section called “Alternating users” (p. 82), you need a separate secret that contains credentials that can update the rotating secret's credentials.

To turn on rotation for an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret (console)

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

2. On the Secrets page, choose your secret.

3. On the Secret details page, in the Rotation conﬁguration section, choose Edit rotation.

4. In the Edit rotation conﬁguration dialog box, do the following:

a. Turn on Automatic rotation.

b. Under Rotation schedule, enter your schedule in UTC time zone by doing one of the following:

• Choose Schedule expression builder to build a schedule in a form. Secrets Manager stores your schedule as a rate() or cron() expression. The rotation window automatically starts at midnight unless you specify a Start time.

AWS CLI

• Enter the cron expression for your schedule, for example, cron(0 21 L * ? *), which rotates the secret on the last day of every month at 9:00 PM UTC+0. A cron expression for Secrets Manager must have 0 in the minutes ﬁeld because Secrets Manager rotation windows open on the hour. It must have * in the year ﬁeld, because Secrets Manager does not support rotation schedules that are more than a year apart.

For more information, see Schedule expressions (p. 86).

• Enter a rate expression for a daily rate, for example, rate(10 days), which rotates the secret every 10 days. The expression must include rate(). With a rate expression, the rotation window automatically starts at midnight.

c. (Optional) For Window duration, choose the length of the window during which you want Secrets Manager to rotate your secret, for example 3h for a three hour window. The window must not go into the next UTC day. The rotation window automatically ends at the end of the day if you don't specify Window duration.

d. (Optional) Choose Rotate immediately when the secret is stored to rotate your secret when you save your changes. If you clear the checkbox, then the ﬁrst rotation will begin on the schedule you set.

If you use the section called “Alternating users” (p. 82), the credentials in the previous version of the secret are still valid and can be used to access the database or service. To meet compliance requirements, you might need to rotate your secrets more often. For example, if your credential lifetime maximum is 90 days, then we recommend you set your rotation interval to 44 days. That way both users' credentials will be updated within 90 days.

e. Under Rotation function, do the following:

• To have Secrets Manager create a rotation function for you based on the Rotation function templates (p. 94) for your secret, choose Create a new Lambda function and enter a name for your new function. Secrets Manager adds "SecretsManager" to the beginning of your function name.

• To use a rotation function that you or Secrets Manager already created, choose Use an existing Lambda function. You can reuse a rotation function you used for another secret if the rotation strategy is the same.

f. For Use separate credentials to rotate this secret, do one of the following:

• For the Single user rotation strategy (p. 81), choose No.

• For the the section called “Alternating users” (p. 82), choose Yes. Then choose a secret that contains a user with elevated credentials.

For help resolving common rotation issues, see the section called “Troubleshoot rotation” (p. 131).

AWS CLI

To turn on rotation, see rotate-secret.

AWS SDK

To turn on rotation, use the RotateSecret action. For more information, see the section called “AWS SDKs” (p. 8).

Automatically rotate another type of secret

Secrets Manager provides complete rotation templates for Amazon RDS, Amazon DocumentDB, and Amazon Redshift secrets. For more information, see the section called “Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret” (p. 83).

Other type of secret

For other types of secrets, you create your own rotation function. Secrets Manager provides a the section called “Generic rotation function template” (p. 100) that you can use as a starting point. If you use the Secrets Manager console or AWS Serverless Application Repository console to create your function from the template, then the Lambda execution role is also automatically set up.

Another way to automatically rotate a secret is to use AWS CloudFormation to create the secret, and include AWS::SecretsManager::RotationSchedule. See Automate secret creation in AWS CloudFormation.

Before you begin, you need the following:

• A secret with the information you want to rotate, for example credentials for a user of a database or service.

To turn on rotation (console)

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

2. On the Secrets page, choose your secret.

3. On the Secret details page, in the Rotation conﬁguration section, choose Edit rotation. The Edit rotation conﬁguration dialog box opens. Do the following:

a. Turn on Automatic rotation.

b. Under Rotation schedule, enter your schedule in UTC time zone by doing one of the following:

• Choose Schedule expression, and then do one of the following:

在文檔中 AWS Secrets Manager (頁 83-117)