CreateSecret - Key Management Service - Alibaba Cloud Documentation Center

You must specify the secret name, the secret value that is stored in the initial version, and the version number. The initial version is labeled as ACSCurrent.

Key Management Service (KMS) uses a key to encrypt the secret value. The key and the secret must belong to the same KMS instance, and the key must be a symmetric key.

Note KMS encrypts the secret value of each version. Metadata such as the secret name, version number, and stage label of the version are not encrypted.

Before you can encrypt a secret value, you must have the kms:GenerateDataKey permission on the key that is used to encrypt the secret value.

This topic provides an example on how to create an ApsaraDB RDS secret whose name is mydbconninfo, initial version VersionId is v1, and secret value SecretData is {"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	CreateSecret	The operation that you want to perform. Set the value to CreateSecret.
SecretName	String	Yes	mydbconninfo	The name of the secret. The name can be up to 192 characters in length, and can contain letters, digits, underscores (_), forward slashes (/), plus signs (+), equal signs (=), periods (.), hyphens (-), and at signs (@). The following list describes the name requirements for different types of secrets: If SecretType is set to Generic or Rds, the name cannot start with `acs/`. If SecretType is set to RAMCredentials, set the value to `$Auto`. In this case, KMS automatically generates a secret name that starts with `acs/ram/user/`. The name includes the display name of a required Resource Access Management (RAM) user. If SecretType is set to ECS, the name must start with `acs/ecs/`.
VersionId	String	Yes	v1	The initial version number. The version number is unique within the secret. The version number can be up to 64 characters in length.
EncryptionKeyId	String	No	key-gzz63ff0db5hg3qje****	The ID of the key that is used to encrypt the secret value. Note The key and the secret must belong to the same KMS instance, and the key must be a symmetric key.
SecretData	String	Yes	{"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}	The secret value. The value can be up to 30,720 bytes in length, which is equivalent to 30 KB in size. KMS uses the specified key to encrypt the secret value and then stores the secret value in the initial version. If SecretType is set to Generic, you can configure a custom secret value. If SecretType is set to Rds, the secret value is in the `{"Accounts":[{"AccountName":"","AccountPassword":""}]}` format. In the preceding format, `AccountName` indicates the username of the account that is used to connect to your ApsaraDB RDS instance, and `AccountPassword` specifies the password of the account. If SecretType is set to RAMCredentials, the secret value is in the `{"AccessKeys":[{"AccessKeyId":"","AccessKeySecret":""}]}` format. In the preceding format, `AccessKeyId` indicates the AccessKey ID of the RAM user and `AccessKeySecret` indicates the AccessKey secret of the RAM user. You must specify all the AccessKey pairs of the RAM user. If SecretType is set to ECS, the secret value must be in one the following formats: `{"UserName":"","Password": ""}`: This format is used when the value of SecretSubType is set to Password. In the format, `UserName` indicates the username that is used to log on to the ECS instance, and `Password` indicates the password that is used to log on to the ECS instance. `{"UserName":"","PublicKey": "", "PrivateKey": ""}`: This format is used when the value of SecretSubType is set to SSHKey. In the format, `PublicKey` indicates the SSH public key that is used to log on to the ECS instance, and `PrivateKey` specifies the SSH private key that is used to log on to the ECS instance.
SecretDataType	String	No	text	The type of the secret value. Valid values: text (default) binary Note If SecretType is set to Rds, RAMCredentials, or ECS, SecretDataType must be set to text.
Description	String	No	mydbinfo	The description of the secret.
Tags	String	No	[{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]	The tags of the secret. A tag consists of a key-value pair. A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), and at signs (@). A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
SecretType	String	No	Rds	The type of the secret. Valid values: Generic (default): generic secret. Generic: ApsaraDB RDS secret RAMCredentials: RAM secret ECS: ECS secret
ExtendedConfig	Map	No	{"SecretSubType":"SingleUser", "DBInstanceId":"rm-bp1b3dd3a506e****" ,"CustomData":{"Key1": "v1", "fds":"fdsf"}}	The extended configuration of the secret. This parameter specifies the properties of the secret of the specific type. The field value can be up to 1,024 characters in length. If SecretType is set to Generic, you do not need to configure this parameter. If SecretType is set to Rds, you must configure the following fields in the ExtendedConfig parameter: SecretSubType: required. The subtype of the secret. Valid values: SingleUser: Secrets Manager manages the ApsaraDB RDS secret in single-account mode. When the secret is rotated, the password of the specified account is reset to a new random password. DoubleUsers: Secrets Manager manages the ApsaraDB RDS secret in dual-account mode. One account is referenced by the ACSCurrent version, and the other account is referenced by the ACSPrevious version. When the secret is rotated, the password of the account referenced by the ACSPrevious version is reset to a new random password. Then, Secrets Manager switches the referenced accounts between the ACSCurrent and ACSPrevious versions. DBInstanceId: required. The ApsaraDB RDS instance to which the ApsaraDB RDS account belongs. CustomData: optional. The custom data. The value is a collection of key-value pairs in the JSON format. Up to 10 key-value pairs can be specified. Separate multiple key-value pairs with commas (,). Example: `{"Key1": "v1", "fds":"fdsf"}`. The default value is a pair of empty braces (`{}`). If SecretType is set to RAMCredentials, you must configure the following fields in the ExtendedConfig parameter: SecretSubType: required. The subtype of the secret. Set the value to RamUserAccessKey. UserName: required. The name of the RAM user. CustomData: optional. The custom data. The value is a collection of key-value pairs in the JSON format. Up to 10 key-value pairs can be specified. Separate multiple key-value pairs with commas (,). The default value is a pair of empty braces (`{}`). If SecretType is set to ECS, you must configure the following fields in the ExtendedConfig parameter: SecretSubType: required. The subtype of the secret. Valid values: Password: the password that is used to log on to the ECS instance. SSHKey: the SSH public key and private key that are used to log on to the ECS instance. RegionId: required. The ID of the region in which the ECS instance resides. InstanceId: required. The ID of the ECS instance. CustomData: optional. The custom data. The value is a collection of key-value pairs in the JSON format. Up to 10 key-value pairs can be specified. Separate multiple key-value pairs with commas (,). The default value is a pair of empty braces (`{}`). Note This parameter is required if you set SecretType to Rds, RAMCredentials, or ECS.
EnableAutomaticRotation	Boolean	No	true	Specifies whether to enable automatic rotation. Valid values: true false (default) Note This parameter takes effect only when SecretType is set to Rds, RAMCredentials, or ECS. If SecretType is set to Generic, automatic rotation is not supported. You can call the PutSecretValue operation to manually rotate a generic secret.
RotationInterval	String	No	30d	The interval for automatic rotation. Valid values: 6 hours to 8,760 hours (365 days). The value is in the `integer[unit]` format. The unit can be d (day), h (hour), m (minute), or s (second). For example, both 7d and 604800s indicate a seven-day interval. Note This parameter is required only when EnableAutomaticRotation is set to true.
DKMSInstanceId	String	No	kst-bjj62d8f5e0sgtx8h****	The ID of the KMS instance.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter	Type	Example	Description
RequestId	String	3bf02f7a-015b-4f93-be0f-cc043fda2dd3	The ID of the request, which is used to locate and troubleshoot issues.
AutomaticRotation	String	Enabled	Specifies whether to enable automatic rotation. Valid values: Enabled: indicates that automatic rotation is enabled. Disabled: indicates that automatic rotation is disabled. Invalid: indicates that the status of automatic rotation is abnormal. In this case, Secrets Manager cannot automatically rotate the secret. Note This parameter is returned if you set SecretType to Rds, RAMCredentials, or ECS.
SecretName	String	mydbconninfo	The name of the secret.
VersionId	String	v1	The version number of the secret.
NextRotationDate	String	2023-07-06T18:22:03Z	The time when the next rotation will be performed. Note This parameter is returned if automatic rotation is enabled.
SecretType	String	Rds	The type of the secret. Valid values: Generic: generic secret Generic: ApsaraDB RDS secret RAMCredentials: RAM secret ECS: ECS secret
RotationInterval	String	604800s	The interval for automatic rotation. The value is in the `integer[unit]` format. The `unit` field has a fixed value of s. For example, if the value is 604800s, automatic rotation is performed at a 7-day interval. Note This parameter is returned if automatic rotation is enabled.
Arn	String	acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo	The Alibaba Cloud Resource Name (ARN) of the secret.
ExtendedConfig	String	{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":"Key1": "v1", "fds":"fdsf"} }	The extended configuration of the secret. Note This parameter is returned if you set SecretType to Rds, RAMCredentials, or ECS.
DKMSInstanceId	String	kst-bjj62d8f5e0sgtx8h****	The ID of the KMS instance.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateSecret
&SecretName=mydbconninfo
&VersionId=v1
&EncryptionKeyId=key-gzz63ff0db5hg3qje****
&SecretData={"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}
&SecretDataType=text
&Description=mydbinfo
&Tags=[{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]
&SecretType=Rds
&EnableAutomaticRotation=true
&RotationInterval=30d
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateSecretResponse>
    <RequestId>3bf02f7a-015b-4f93-be0f-cc043fda2dd3</RequestId>
    <AutomaticRotation>Enabled</AutomaticRotation>
    <SecretName>mydbconninfo</SecretName>
    <VersionId>v1</VersionId>
    <NextRotationDate>2023-07-06T18:22:03Z</NextRotationDate>
    <SecretType>Rds</SecretType>
    <RotationInterval>604800s</RotationInterval>
    <Arn>acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo</Arn>
    <ExtendedConfig>{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\",  \"CustomData\":"Key1": "v1", "fds":"fdsf"} }</ExtendedConfig>
    <DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
</CreateSecretResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "3bf02f7a-015b-4f93-be0f-cc043fda2dd3",
  "AutomaticRotation" : "Enabled",
  "SecretName" : "mydbconninfo",
  "VersionId" : "v1",
  "NextRotationDate" : "2023-07-06T18:22:03Z",
  "SecretType" : "Rds",
  "RotationInterval" : "604800s",
  "Arn" : "acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo",
  "ExtendedConfig" : "{\\\"SecretSubType\\\":\\\"SingleUser\\\", \\\"DBInstanceId\\\":\\\"rm-uf667446pc955****\\\",  \\\"CustomData\\\":\"Key1\": \"v1\", \"fds\":\"fdsf\"} }",
  "DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
}

Error codes

HttpCode	Error code	Error message	Description
400	UnsupportedOperation	This action is not supported.	The operation is not supported.
400	Rejected.LimitExceeded	The request was rejected because user create resource limit was exceeded	The request is rejected because the number of created resources reaches the upper limit.
403	Forbidden.DKMSInstanceNotFound	The specified DKMS Instance is not found.	Your dedicated KMS instance is not found.
404	Forbidden.ResourceNotFound	The resource is not found.	The specified resource does not exist.
409	Rejected.ResourceExist	The resource already exists.	The specified resource already exists.
409	Rejected.ResourceInDeleteWindow	The secret is planned to be deleted.	The secret is to be deleted.

For a list of error codes, see Service error codes.