docs: explain procedure for rotating a SecretsManager Secret (#20989)

CloudFormation will not automatically check all Secrets for their
values, so it is up to the user to incude a change in the resource
that uses a Secret, so that CloudFormation will re-read the value.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/@aws-cdk/aws-codepipeline-actions/lib/github/source-action.ts

@@ -67,6 +67,9 @@ export interface GitHubSourceActionProps extends codepipeline.CommonActionProps
    *   const oauth = cdk.SecretValue.secretsManager('my-github-token');
    *   new GitHubSource(this, 'GitHubAction', { oauthToken: oauth, ... });
    *
+   * If you rotate the value in the Secret, you must also change at least one property
+   * of the CodePipeline to force CloudFormation to re-read the secret.
+   *
    * The GitHub Personal Access Token should have these scopes:
    *
    * * **repo** - to read the repository

packages/@aws-cdk/core/README.md

@@ -276,6 +276,13 @@ exposed where they shouldn't be. If you try to use a `SecretValue` in a
 different location, an error about unsafe secret usage will be thrown at
 synthesis time.
 
+If you rotate the secret's value in Secrets Manager, you must also change at
+least one property on the resource where you are using the secret, to force
+CloudFormation to re-read the secret.
+
+`SecretValue.ssmSecure()` is only supported for a limited set of resources.
+[Click here for a list of supported resources and properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#template-parameters-dynamic-patterns-resources).
+
 ## ARN manipulation
 
 Sometimes you will need to put together or pick apart Amazon Resource Names

packages/@aws-cdk/core/lib/secret-value.ts

@@ -76,6 +76,10 @@ export class SecretValue extends Intrinsic {
 
   /**
    * Creates a `SecretValue` with a value which is dynamically loaded from AWS Secrets Manager.
+   *
+   * If you rotate the value in the Secret, you must also change at least one property
+   * on the resource where you are using the secret, to force CloudFormation to re-read the secret.
+   *
    * @param secretId The ID or ARN of the secret
    * @param options Options
    */
@@ -107,6 +111,10 @@ export class SecretValue extends Intrinsic {
   /**
    * Use a secret value stored from a Systems Manager (SSM) parameter.
    *
+   * This secret source in only supported in a limited set of resources and
+   * properties. [Click here for the list of supported
+   * properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#template-parameters-dynamic-patterns-resources).
+   *
    * @param parameterName The name of the parameter in the Systems Manager
    * Parameter Store. The parameter name is case-sensitive.
    *

packages/@aws-cdk/pipelines/lib/codepipeline/codepipeline-source.ts

@@ -34,6 +34,9 @@ export abstract class CodePipelineSource extends Step implements ICodePipelineAc
    * Authentication will be done by a secret called `github-token` in AWS
    * Secrets Manager (unless specified otherwise).
    *
+   * If you rotate the value in the Secret, you must also change at least one property
+   * on the Pipeline, to force CloudFormation to re-read the secret.
+   *
    * The token should have these permissions:
    *
    * * **repo** - to read the repository

packages/aws-cdk-lib/README.md

@@ -307,6 +307,13 @@ exposed where they shouldn't be. If you try to use a `SecretValue` in a
 different location, an error about unsafe secret usage will be thrown at
 synthesis time.
 
+If you rotate the secret's value in Secrets Manager, you must also change at
+least one property on the resource where you are using the secret, to force
+CloudFormation to re-read the secret.
+
+`SecretValue.ssmSecure()` is only supported for a limited set of resources.
+[Click here for a list of supported resources and properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#template-parameters-dynamic-patterns-resources).
+
 ## ARN manipulation
 
 Sometimes you will need to put together or pick apart Amazon Resource Names