AWS CLI & Secrets Manager: Complete Guide with examples
Introduction
AWS Secret Manager allows you to store sensitive data like passwords, API keys, certificates, and other secrets securely in the cloud. When you create a secret, you define what kind of information should be stored, how long it should last, and who has access to it. Secrets manager also provides additional features such as rotation of credentials, encryption at rest, and automatic expiration of credentials.
With Secrets Manager, you can replace hardcoded credentials in your code, including passwords. You can retrieve secrets programmatically with an API call to Secrets Manager.
In this article, we will look at how to use the AWS CLI to perform common Secrets Manager operations.
Table of contents
- Introduction
- How to create a new secret?
- How to list all secrets?
- How to retrieve a secret value?
- How to modify an existing secret?
- How to list all versions of a secret?
- How to list all versions of a secret?
- How to delete a secret?
Prerequisites
- AWS CLI
- AWS Credentials: If you haven’t setup your AWS credentials before, this resource from AWS is helpful.
How to create a new secret?
We will be using the create-secret
subcommand to create a new secret. The arguments needed for this command are:
name
: Name of the secret you want to createsecret-binary
: Value of the secret in binary formatsecret-string
: Value of the secret in string formatkms-key-id
(optional): Custom KMS key to be used to encrypt the secret. By default, Secrets Manager uses the AWS managed keyaws/secretsmanager
.
You only need to provide either the secret value in binary or string format.
aws secretsmanager create-secret --name my-test-secret --secret-string test-secret-value
Output:
{
"ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret",
"VersionId": "773cae67-c42a-451d-a1b2-596142157a4b"
}
How to list all secrets?
We can use the list-secrets
subcommand to list all the secrets in your AWS account.
aws secretsmanager list-secrets
Output:
{
"SecretList": [
{
"ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret",
"LastChangedDate": "2022-08-28T14:28:15.440000-07:00",
"SecretVersionsToStages": {
"773cae67-c42a-451d-a1b2-596142157a4b": [
"AWSCURRENT"
]
},
"CreatedDate": "2022-08-28T14:28:15.405000-07:00"
}
]
}
How to retrieve a secret value?
We will use the get-secret-value
subcommand to retrieve the value of the secret. The arguments needed for this command are:
secret-id
: ARN or Name of the secret to retrieve.version-id
: ID of the version to retrieve
aws secretsmanager get-secret-value --secret-id my-test-secret
Output:
{
"ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret",
"VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
"SecretString": "test-secret-value",
"VersionStages": [
"AWSCURRENT"
],
"CreatedDate": "2022-08-28T14:28:15.435000-07:00"
}
How to modify an existing secret?
We can update the secret using the update-secret
subcommand. Secrets are immutable. update-secret
does not modify the existing secret. Instead, it creates a new version of the secret.
aws secretsmanager update-secret --secret-id my-test-secret --secret-string update-secret-value
Output:
{
"ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret",
"VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8"
}
How to list all versions of a secret?
We can use the list-secret-version-ids
command to list all versions of a particular secret.
aws secretsmanager list-secret-version-ids --secret-id my-test-secret
Output:
{
"Versions": [
{
"VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
"VersionStages": [
"AWSPREVIOUS"
],
"LastAccessedDate": "2022-08-27T17:00:00-07:00",
"CreatedDate": "2022-08-28T14:28:15.435000-07:00",
"KmsKeyIds": [
"DefaultEncryptionKey"
]
},
{
"VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8",
"VersionStages": [
"AWSCURRENT"
],
"CreatedDate": "2022-08-28T14:43:35.596000-07:00",
"KmsKeyIds": [
"DefaultEncryptionKey"
]
}
],
"ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret"
}
How to list all versions of a secret?
We can use the list-secret-version-ids
command to list all versions of a particular secret.
aws secretsmanager list-secret-version-ids --secret-id my-test-secret
Output:
{
"Versions": [
{
"VersionId": "773cae67-c42a-451d-a1b2-596142157a4b",
"VersionStages": [
"AWSPREVIOUS"
],
"LastAccessedDate": "2022-08-27T17:00:00-07:00",
"CreatedDate": "2022-08-28T14:28:15.435000-07:00",
"KmsKeyIds": [
"DefaultEncryptionKey"
]
},
{
"VersionId": "fd3381fb-260b-47a6-88ef-f2a8a56a10c8",
"VersionStages": [
"AWSCURRENT"
],
"CreatedDate": "2022-08-28T14:43:35.596000-07:00",
"KmsKeyIds": [
"DefaultEncryptionKey"
]
}
],
"ARN": "arn:aws:secretsmanager:us-west-1:xxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret"
}
How to delete a secret?
We can use the delete-secret
command to delete a secret and all its versions. By default, any deleted secrets can be retrieved within 30
days of deletion.
Arguments used in this command:
recovery-window-in-days
: Number of days (between 7 to 30 days) that Secrets Manager waits before permanently deleting the secretforce-delete-without-recovery
: Whether to delete the secret without any recovery
aws secretsmanager delete-secret --secret-id my-test-secret
Output:
{
"ARN": "arn:aws:secretsmanager:us-west-1:xxxx:secret:my-test-secret-kOVjat",
"Name": "my-test-secret",
"DeletionDate": "2022-09-27T15:07:24.259000-07:00"
}