Add AWS Secrets Manager API key storage details

[litianningdatadog]

What does this PR do? What is the motivation?

Merge instructions

Merge readiness:

• Ready for merge

For Datadog employees:

Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

[6/5/2025] Merge queue has been disabled on the documentation repo. If you have write access to the repo, the PR has been reviewed by a Documentation team member, and all of the required checks have passed, you can use the Squash and Merge button to merge the PR. If you don't have write access, or you need help, reach out in the #documentation channel in Slack.

AI assistance

Additional notes

[chatgpt-codex-connector]

💡 Codex Review

documentation/content/en/serverless/aws_lambda/configuration.md

Line 805 in c91116b

`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. The Lambda function's execution role must be granted secretsmanager:GetSecretValue permission on the referenced ARN.

Include KMS decrypt permission for CMK-backed secrets

When the referenced Secrets Manager secret is encrypted with a customer-managed KMS key, granting only secretsmanager:GetSecretValue is not enough; the Lambda execution role also needs kms:Decrypt on that key, otherwise the extension cannot read the API key even though the documented permission is present. Please mention the KMS permission in this Secrets Manager setup text so users with CMK-backed secrets do not deploy a non-reporting function.

---

documentation/content/en/serverless/aws_lambda/configuration.md

Lines 807 to 809 in c91116b

	Starting v96, the secret value can be stored in either of two formats:
	- Plain string: the secret value is used directly as the API key.
	- JSON object: if the secret value parses as a JSON object containing a `dd_api_key` field, the value of that field is extracted and used as the API key. This is convenient when the same secret stores multiple credentials (for example, alongside an app key or other tokens).

Align install docs before recommending JSON secrets

This new section says v96 accepts a JSON object with dd_api_key, but the same serverless Lambda instrumentation pages still repeatedly tell users that DD_API_KEY_SECRET_ARN secrets “need to be stored as a plaintext string (not a JSON blob)” for the current v96 examples (for example, content/en/serverless/aws_lambda/instrumentation/python.md). As published together, users following the install pages for v96 get the opposite instruction from this configuration page, so the existing plaintext-only guidance should be updated or this section should be qualified before adding the JSON format.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[litianningdatadog]

#36520

[estherk15]

Should this section go before "Reload API key secret periodically"?

[estherk15]

Suggested change

	## Store API key in AWS Secrets Manager
	## Store the API key in AWS Secrets Manager

[estherk15]

Suggested change

	`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. The Lambda function's execution role must be granted secretsmanager:GetSecretValue permission on the referenced ARN.
	`DD_API_KEY_SECRET_ARN` specifies the ARN of an AWS Secrets Manager secret that stores your Datadog API key. When set, the Datadog Lambda Extension fetches the secret at cold start and uses its value as the API key. Grant the Lambda function's execution role `secretsmanager:GetSecretValue` permission on the referenced ARN.

[estherk15]

Suggested change

	Starting v96, the secret value can be stored in either of two formats:
	Starting with version 96, you can store the secret value in one of the following formats:

[estherk15]

Suggested change

	- Plain string: the secret value is used directly as the API key.
	- JSON object: if the secret value parses as a JSON object containing a `dd_api_key` field, the value of that field is extracted and used as the API key. This is convenient when the same secret stores multiple credentials (for example, alongside an app key or other tokens).
	- **Plain string**: The extension uses the secret value as the API key.
	- **JSON object**: If the secret value parses as a JSON object containing a `dd_api_key` field, the extension extracts that field's value and uses it as the API key. This is useful when the same secret stores multiple credentials (for example, alongside an app key or other tokens).

[estherk15]

Suggested change

	Attention: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as dd_api_key and is not configurable.
	**Note**: If the JSON object does not contain a `dd_api_key` field, or the value is not valid JSON, the extension falls back to using the raw secret string. The JSON key name is fixed as `dd_api_key` and is not configurable.

[estherk15]

Is json correct? If not, spell out shell instead of sh

Suggested change

	```sh
	{ "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
	```
	```json
	{ "dd_api_key": "<YOUR_DATADOG_API_KEY>" }
	```