From 3f9a4c4fd52828371d8b7d455cd6c2ffa8a6a14c Mon Sep 17 00:00:00 2001 From: awstools Date: Thu, 18 Jul 2024 19:31:30 +0000 Subject: [PATCH] docs(client-secrets-manager): Doc only update for Secrets Manager --- .../src/auth/httpAuthSchemeProvider.ts | 2 +- .../src/commands/CreateSecretCommand.ts | 3 ++ .../src/commands/PutSecretValueCommand.ts | 3 ++ .../src/commands/UpdateSecretCommand.ts | 5 ++- .../src/models/models_0.ts | 2 +- .../aws-models/secrets-manager.json | 34 +++++++++---------- 6 files changed, 29 insertions(+), 20 deletions(-) diff --git a/clients/client-secrets-manager/src/auth/httpAuthSchemeProvider.ts b/clients/client-secrets-manager/src/auth/httpAuthSchemeProvider.ts index 3a52e3510243..0a8df572ddeb 100644 --- a/clients/client-secrets-manager/src/auth/httpAuthSchemeProvider.ts +++ b/clients/client-secrets-manager/src/auth/httpAuthSchemeProvider.ts @@ -60,7 +60,7 @@ function createAwsAuthSigv4HttpAuthOption(authParameters: SecretsManagerHttpAuth name: "secretsmanager", region: authParameters.region, }, - propertiesExtractor: (config: SecretsManagerClientConfig, context) => ({ + propertiesExtractor: (config: Partial, context) => ({ /** * @internal */ diff --git a/clients/client-secrets-manager/src/commands/CreateSecretCommand.ts b/clients/client-secrets-manager/src/commands/CreateSecretCommand.ts index 69783ae67093..a125c2740932 100644 --- a/clients/client-secrets-manager/src/commands/CreateSecretCommand.ts +++ b/clients/client-secrets-manager/src/commands/CreateSecretCommand.ts @@ -64,6 +64,9 @@ export interface CreateSecretCommandOutput extends CreateSecretResponse, __Metad * IAM policy actions for Secrets Manager and Authentication * and access control in Secrets Manager.

*

To encrypt the secret with a KMS key other than aws/secretsmanager, you need kms:GenerateDataKey and kms:Decrypt permission to the key.

+ * + *

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

+ * * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript diff --git a/clients/client-secrets-manager/src/commands/PutSecretValueCommand.ts b/clients/client-secrets-manager/src/commands/PutSecretValueCommand.ts index d9059f93e2c2..6e4be8afbaac 100644 --- a/clients/client-secrets-manager/src/commands/PutSecretValueCommand.ts +++ b/clients/client-secrets-manager/src/commands/PutSecretValueCommand.ts @@ -60,6 +60,9 @@ export interface PutSecretValueCommandOutput extends PutSecretValueResponse, __M * For more information, see * IAM policy actions for Secrets Manager and Authentication * and access control in Secrets Manager.

+ * + *

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

+ * * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript diff --git a/clients/client-secrets-manager/src/commands/UpdateSecretCommand.ts b/clients/client-secrets-manager/src/commands/UpdateSecretCommand.ts index 7e63a8d2ccd2..9705f4babae2 100644 --- a/clients/client-secrets-manager/src/commands/UpdateSecretCommand.ts +++ b/clients/client-secrets-manager/src/commands/UpdateSecretCommand.ts @@ -53,8 +53,11 @@ export interface UpdateSecretCommandOutput extends UpdateSecretResponse, __Metad * IAM policy actions for Secrets Manager and Authentication * and access control in Secrets Manager. * If you use a customer managed key, you must also have kms:GenerateDataKey, kms:Encrypt, and - * kms:Decrypt permissions on the key. If you change the KMS key and you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-ecrypt existing secret versions with the new key. For more information, see + * kms:Decrypt permissions on the key. If you change the KMS key and you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-encrypt existing secret versions with the new key. For more information, see * Secret encryption and decryption.

+ * + *

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

+ * * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript diff --git a/clients/client-secrets-manager/src/models/models_0.ts b/clients/client-secrets-manager/src/models/models_0.ts index 97795d54c364..defffe7e6545 100644 --- a/clients/client-secrets-manager/src/models/models_0.ts +++ b/clients/client-secrets-manager/src/models/models_0.ts @@ -2095,7 +2095,7 @@ export interface UpdateSecretRequest { /** *

The ARN, key ID, or alias of the KMS key that Secrets Manager * uses to encrypt new secret versions as well as any existing versions with the staging labels - * AWSCURRENT, AWSPENDING, or AWSPREVIOUS. If you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-ecrypt existing secret versions with the new key. For more information about versions and staging labels, see Concepts: Version.

+ * AWSCURRENT, AWSPENDING, or AWSPREVIOUS. If you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-encrypt existing secret versions with the new key. For more information about versions and staging labels, see Concepts: Version.

*

A key alias is always prefixed by alias/, for example alias/aws/secretsmanager. * For more information, see About aliases.

*

If you set this to an empty string, Secrets Manager uses the Amazon Web Services managed key diff --git a/codegen/sdk-codegen/aws-models/secrets-manager.json b/codegen/sdk-codegen/aws-models/secrets-manager.json index f4cba1801823..d280cad1906d 100644 --- a/codegen/sdk-codegen/aws-models/secrets-manager.json +++ b/codegen/sdk-codegen/aws-models/secrets-manager.json @@ -350,7 +350,7 @@ } ], "traits": { - "smithy.api#documentation": "

Creates a new secret. A secret can be a password, a set of \n credentials such as a user name and password, an OAuth token, or other secret information \n that you store in an encrypted form in Secrets Manager. The secret also \n includes the connection information to access a database or other service, which Secrets Manager \n doesn't encrypt. A secret in Secrets Manager consists of both the protected secret data and the\n important information needed to manage the secret.

\n

For secrets that use managed rotation, you need to create the secret through the managing service. For more information, see Secrets Manager secrets managed by other Amazon Web Services services.\n\n

\n

For information about creating a secret in the console, see Create a secret.

\n

To create a secret, you can provide the secret value to be encrypted in either the\n SecretString parameter or the SecretBinary parameter, but not both. \n If you include SecretString or SecretBinary\n then Secrets Manager creates an initial secret version and automatically attaches the staging\n label AWSCURRENT to it.

\n

For database credentials you want to rotate, for Secrets Manager to be able to rotate the secret,\n you must make sure the JSON you store in the SecretString matches the JSON structure of\n a database secret.

\n

If you don't specify an KMS encryption key, Secrets Manager uses the Amazon Web Services managed key \n aws/secretsmanager. If this key \n doesn't already exist in your account, then Secrets Manager creates it for you automatically. All\n users and roles in the Amazon Web Services account automatically have access to use aws/secretsmanager. \n Creating aws/secretsmanager can result in a one-time significant delay in returning the \n result.

\n

If the secret is in a different Amazon Web Services account from the credentials calling the API, then \n you can't use aws/secretsmanager to encrypt the secret, and you must create \n and use a customer managed KMS key.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary or SecretString because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:CreateSecret. If you \n include tags in the secret, you also need secretsmanager:TagResource. To add replica Regions, you must also have secretsmanager:ReplicateSecretToRegions.\n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager.

\n

To encrypt the secret with a KMS key other than aws/secretsmanager, you need kms:GenerateDataKey and kms:Decrypt permission to the key.

", + "smithy.api#documentation": "

Creates a new secret. A secret can be a password, a set of \n credentials such as a user name and password, an OAuth token, or other secret information \n that you store in an encrypted form in Secrets Manager. The secret also \n includes the connection information to access a database or other service, which Secrets Manager \n doesn't encrypt. A secret in Secrets Manager consists of both the protected secret data and the\n important information needed to manage the secret.

\n

For secrets that use managed rotation, you need to create the secret through the managing service. For more information, see Secrets Manager secrets managed by other Amazon Web Services services.\n\n

\n

For information about creating a secret in the console, see Create a secret.

\n

To create a secret, you can provide the secret value to be encrypted in either the\n SecretString parameter or the SecretBinary parameter, but not both. \n If you include SecretString or SecretBinary\n then Secrets Manager creates an initial secret version and automatically attaches the staging\n label AWSCURRENT to it.

\n

For database credentials you want to rotate, for Secrets Manager to be able to rotate the secret,\n you must make sure the JSON you store in the SecretString matches the JSON structure of\n a database secret.

\n

If you don't specify an KMS encryption key, Secrets Manager uses the Amazon Web Services managed key \n aws/secretsmanager. If this key \n doesn't already exist in your account, then Secrets Manager creates it for you automatically. All\n users and roles in the Amazon Web Services account automatically have access to use aws/secretsmanager. \n Creating aws/secretsmanager can result in a one-time significant delay in returning the \n result.

\n

If the secret is in a different Amazon Web Services account from the credentials calling the API, then \n you can't use aws/secretsmanager to encrypt the secret, and you must create \n and use a customer managed KMS key.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary or SecretString because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:CreateSecret. If you \n include tags in the secret, you also need secretsmanager:TagResource. To add replica Regions, you must also have secretsmanager:ReplicateSecretToRegions.\n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager.

\n

To encrypt the secret with a KMS key other than aws/secretsmanager, you need kms:GenerateDataKey and kms:Decrypt permission to the key.

\n \n

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

\n ", "smithy.api#examples": [ { "title": "To create a basic secret", @@ -1881,7 +1881,7 @@ } ], "traits": { - "smithy.api#documentation": "

Creates a new version with a new encrypted secret value and attaches it to the secret. The \n version can contain a new SecretString value or a new SecretBinary value.

\n

We recommend you avoid calling PutSecretValue at a sustained rate of more than \n once every 10 minutes. When you update the secret value, Secrets Manager creates a new version \n of the secret. Secrets Manager removes outdated versions when there are more than 100, but it does not \n remove versions created less than 24 hours ago. If you call PutSecretValue more \n than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach \n the quota for secret versions.

\n

You can specify the staging labels to attach to the new version in VersionStages. \n If you don't include VersionStages, then Secrets Manager automatically\n moves the staging label AWSCURRENT to this version. If this operation creates \n the first version for the secret, then Secrets Manager\n automatically attaches the staging label AWSCURRENT to it. \n If this operation moves the staging label AWSCURRENT from another version to this\n version, then Secrets Manager also automatically moves the staging label AWSPREVIOUS to\n the version that AWSCURRENT was removed from.

\n

This operation is idempotent. If you call this operation with a ClientRequestToken \n that matches an existing version's VersionId, and you specify the\n same secret data, the operation succeeds but does nothing. However, if the secret data is\n different, then the operation fails because you can't modify an existing version; you can\n only create new ones.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary, SecretString, or RotationToken because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:PutSecretValue. \n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager.

", + "smithy.api#documentation": "

Creates a new version with a new encrypted secret value and attaches it to the secret. The \n version can contain a new SecretString value or a new SecretBinary value.

\n

We recommend you avoid calling PutSecretValue at a sustained rate of more than \n once every 10 minutes. When you update the secret value, Secrets Manager creates a new version \n of the secret. Secrets Manager removes outdated versions when there are more than 100, but it does not \n remove versions created less than 24 hours ago. If you call PutSecretValue more \n than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach \n the quota for secret versions.

\n

You can specify the staging labels to attach to the new version in VersionStages. \n If you don't include VersionStages, then Secrets Manager automatically\n moves the staging label AWSCURRENT to this version. If this operation creates \n the first version for the secret, then Secrets Manager\n automatically attaches the staging label AWSCURRENT to it. \n If this operation moves the staging label AWSCURRENT from another version to this\n version, then Secrets Manager also automatically moves the staging label AWSPREVIOUS to\n the version that AWSCURRENT was removed from.

\n

This operation is idempotent. If you call this operation with a ClientRequestToken \n that matches an existing version's VersionId, and you specify the\n same secret data, the operation succeeds but does nothing. However, if the secret data is\n different, then the operation fails because you can't modify an existing version; you can\n only create new ones.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary, SecretString, or RotationToken because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:PutSecretValue. \n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager.

\n \n

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

\n ", "smithy.api#examples": [ { "title": "To store a secret value in a new version of a secret", @@ -3176,8 +3176,21 @@ } ], "traits": { - "smithy.api#documentation": "

Modifies the details of a secret, including metadata and the secret value. To change the secret value, you can also use PutSecretValue.

\n

To change the rotation configuration of a secret, use RotateSecret instead.

\n

To change a secret so that it is managed by another service, you need to recreate the secret in that service. See Secrets Manager secrets managed by other Amazon Web Services services.

\n

We recommend you avoid calling UpdateSecret at a sustained rate of more than \n once every 10 minutes. When you call UpdateSecret to update the secret value, Secrets Manager creates a new version \n of the secret. Secrets Manager removes outdated versions when there are more than 100, but it does not \n remove versions created less than 24 hours ago. If you update the secret value more \n than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach \n the quota for secret versions.

\n

If you include SecretString or SecretBinary to create a new\n secret version, Secrets Manager automatically moves the staging label AWSCURRENT to the new\n version. Then it attaches the label AWSPREVIOUS\n to the version that AWSCURRENT was removed from.

\n

If you call this operation with a ClientRequestToken that matches an existing version's \n VersionId, the operation results in an error. You can't modify an existing \n version, you can only create a new version. To remove a version, remove all staging labels from it. See \n UpdateSecretVersionStage.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary or SecretString because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:UpdateSecret. \n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager. \n If you use a customer managed key, you must also have kms:GenerateDataKey, kms:Encrypt, and \n kms:Decrypt permissions on the key. If you change the KMS key and you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-ecrypt existing secret versions with the new key. For more information, see \n Secret encryption and decryption.

", + "smithy.api#documentation": "

Modifies the details of a secret, including metadata and the secret value. To change the secret value, you can also use PutSecretValue.

\n

To change the rotation configuration of a secret, use RotateSecret instead.

\n

To change a secret so that it is managed by another service, you need to recreate the secret in that service. See Secrets Manager secrets managed by other Amazon Web Services services.

\n

We recommend you avoid calling UpdateSecret at a sustained rate of more than \n once every 10 minutes. When you call UpdateSecret to update the secret value, Secrets Manager creates a new version \n of the secret. Secrets Manager removes outdated versions when there are more than 100, but it does not \n remove versions created less than 24 hours ago. If you update the secret value more \n than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach \n the quota for secret versions.

\n

If you include SecretString or SecretBinary to create a new\n secret version, Secrets Manager automatically moves the staging label AWSCURRENT to the new\n version. Then it attaches the label AWSPREVIOUS\n to the version that AWSCURRENT was removed from.

\n

If you call this operation with a ClientRequestToken that matches an existing version's \n VersionId, the operation results in an error. You can't modify an existing \n version, you can only create a new version. To remove a version, remove all staging labels from it. See \n UpdateSecretVersionStage.

\n

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary or SecretString because it might be logged. For more information, see Logging Secrets Manager events with CloudTrail.

\n

\n Required permissions: \n secretsmanager:UpdateSecret. \n For more information, see \n IAM policy actions for Secrets Manager and Authentication \n and access control in Secrets Manager. \n If you use a customer managed key, you must also have kms:GenerateDataKey, kms:Encrypt, and \n kms:Decrypt permissions on the key. If you change the KMS key and you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-encrypt existing secret versions with the new key. For more information, see \n Secret encryption and decryption.

\n \n

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store Secrets Manager secrets.

\n ", "smithy.api#examples": [ + { + "title": "To create a new version of the encrypted secret value", + "documentation": "The following example shows how to create a new version of the secret by updating the SecretString field. Alternatively, you can use the put-secret-value operation.", + "input": { + "SecretId": "MyTestDatabaseSecret", + "SecretString": "{JSON STRING WITH CREDENTIALS}" + }, + "output": { + "ARN": "aws:arn:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + "Name": "MyTestDatabaseSecret", + "VersionId": "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE" + } + }, { "title": "To update the description of a secret", "documentation": "The following example shows how to modify the description of a secret.", @@ -3202,19 +3215,6 @@ "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", "Name": "MyTestDatabaseSecret" } - }, - { - "title": "To create a new version of the encrypted secret value", - "documentation": "The following example shows how to create a new version of the secret by updating the SecretString field. Alternatively, you can use the put-secret-value operation.", - "input": { - "SecretId": "MyTestDatabaseSecret", - "SecretString": "{JSON STRING WITH CREDENTIALS}" - }, - "output": { - "ARN": "aws:arn:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", - "Name": "MyTestDatabaseSecret", - "VersionId": "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE" - } } ] } @@ -3245,7 +3245,7 @@ "KmsKeyId": { "target": "com.amazonaws.secretsmanager#KmsKeyIdType", "traits": { - "smithy.api#documentation": "

The ARN, key ID, or alias of the KMS key that Secrets Manager \n uses to encrypt new secret versions as well as any existing versions with the staging labels \n AWSCURRENT, AWSPENDING, or AWSPREVIOUS. If you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-ecrypt existing secret versions with the new key. For more information about versions and staging labels, see Concepts: Version.

\n

A key alias is always prefixed by alias/, for example alias/aws/secretsmanager.\n For more information, see About aliases.

\n

If you set this to an empty string, Secrets Manager uses the Amazon Web Services managed key \n aws/secretsmanager. If this key doesn't already exist in your account, then Secrets Manager \n creates it for you automatically. All users and roles in the Amazon Web Services account automatically have access \n to use aws/secretsmanager. Creating aws/secretsmanager can result in a one-time \n significant delay in returning the result.

\n \n

You can only use the Amazon Web Services managed key aws/secretsmanager if you call this\n operation using credentials from the same Amazon Web Services account that owns the secret. If the secret is in\n a different account, then you must use a customer managed key and provide the ARN of that KMS key in\n this field. The user making the call must have permissions to both the secret and the KMS key in\n their respective accounts.

\n " + "smithy.api#documentation": "

The ARN, key ID, or alias of the KMS key that Secrets Manager \n uses to encrypt new secret versions as well as any existing versions with the staging labels \n AWSCURRENT, AWSPENDING, or AWSPREVIOUS. If you don't have kms:Encrypt permission to the new key, Secrets Manager does not re-encrypt existing secret versions with the new key. For more information about versions and staging labels, see Concepts: Version.

\n

A key alias is always prefixed by alias/, for example alias/aws/secretsmanager.\n For more information, see About aliases.

\n

If you set this to an empty string, Secrets Manager uses the Amazon Web Services managed key \n aws/secretsmanager. If this key doesn't already exist in your account, then Secrets Manager \n creates it for you automatically. All users and roles in the Amazon Web Services account automatically have access \n to use aws/secretsmanager. Creating aws/secretsmanager can result in a one-time \n significant delay in returning the result.

\n \n

You can only use the Amazon Web Services managed key aws/secretsmanager if you call this\n operation using credentials from the same Amazon Web Services account that owns the secret. If the secret is in\n a different account, then you must use a customer managed key and provide the ARN of that KMS key in\n this field. The user making the call must have permissions to both the secret and the KMS key in\n their respective accounts.

\n " } }, "SecretBinary": {