add documetation

website/docs/ephemerals/kms_secrets.html.markdown

@@ -0,0 +1,91 @@
+---
+subcategory: "KMS (Key Management)"
+layout: "aws"
+page_title: "AWS: aws_kms_secrets"
+description: |-
+    Decrypt multiple secrets from data encrypted with the AWS KMS service
+---
+
+# Ephemeral: aws_kms_secrets
+
+Decrypt multiple secrets from data encrypted with the AWS KMS service.
+
+## Example Usage
+
+If you do not already have a `CiphertextBlob` from encrypting a KMS secret, you can use the below commands to obtain one using the [AWS CLI kms encrypt](https://docs.aws.amazon.com/cli/latest/reference/kms/encrypt.html) command. This requires you to have your AWS CLI setup correctly and replace the `--key-id` with your own. Alternatively you can use `--plaintext 'master-password'` (CLIv1) or `--plaintext fileb://<(echo -n 'master-password')` (CLIv2) instead of reading from a file.
+
+-> If you have a newline character at the end of your file, it will be decrypted with this newline character intact. For most use cases this is undesirable and leads to incorrect passwords or invalid values, as well as possible changes in the plan. Be sure to use `echo -n` if necessary.
+-> If you are using asymmetric keys ensure you are using the right encryption algorithm when you encrypt and decrypt else you will get IncorrectKeyException during the decrypt phase.
+
+```console
+% echo -n 'master-password' > plaintext-password
+% aws kms encrypt --key-id ab123456-c012-4567-890a-deadbeef123 --plaintext fileb://plaintext-password --encryption-context foo=bar --output text --query CiphertextBlob
+AQECAHgaPa0J8WadplGCqqVAr4HNvDaFSQ+NaiwIBhmm6qDSFwAAAGIwYAYJKoZIhvcNAQcGoFMwUQIBADBMBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDI+LoLdvYv8l41OhAAIBEIAfx49FFJCLeYrkfMfAw6XlnxP23MmDBdqP8dPp28OoAQ==
+% aws kms encrypt --key-id ab123456-c012-4567-890a-deadbeef123 --plaintext fileb://plaintext-password --encryption-algorithm RSAES_OAEP_SHA_256 --output text --query CiphertextBlob
+AQECAHgaPa0J8WadplGCqqVAr4HNvDaFSQ+NaiwIBhmm6qDSFwAAAGIwYAYJKoZIhvcNAQcGoFMwUQIBADBMBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDI+LoLdvYv8l41OhAAIBEIAfx49FFJCLeYrkfMfAw6XlnxP23MmDBdqP8dPp28OoAQ==
+```
+
+That encrypted output can now be inserted into Terraform configurations without exposing the plaintext secret directly.
+
+```terraform
+ephemeral "aws_kms_secrets" "example" {
+  secret {
+    # ... potentially other configuration ...
+    name    = "master_password"
+    payload = "AQECAHgaPa0J8WadplGCqqVAr4HNvDaFSQ+NaiwIBhmm6qDSFwAAAGIwYAYJKoZIhvcNAQcGoFMwUQIBADBMBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDI+LoLdvYv8l41OhAAIBEIAfx49FFJCLeYrkfMfAw6XlnxP23MmDBdqP8dPp28OoAQ=="
+
+    context = {
+      foo = "bar"
+    }
+  }
+
+  secret {
+    # ... potentially other configuration ...
+    name    = "master_username"
+    payload = "AQECAHgaPa0J8WadplGCqqVAr4HNvDaFSQ+NaiwIBhmm6qDSFwAAAGIwYAYJKoZIhvcNAQcGoFMwUQIBADBMBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDI+LoLdvYv8l41OhAAIBEIAfx49FFJCLeYrkfMfAw6XlnxP23MmDBdqP8dPp28OoAQ=="
+  }
+}
+
+resource "aws_rds_cluster" "example" {
+  # ... other configuration ...
+  master_password = data.aws_kms_secrets.example.plaintext["master_password"]
+  master_username = data.aws_kms_secrets.example.plaintext["master_username"]
+}
+
+ephemeral "aws_kms_secrets" "example" {
+  secret {
+    # ... potentially other configuration ...
+    name    = "app_specific_secret"
+    payload = "AQECAHgaPa0J8WadplGCqqVAr4HNvDaFSQ+NaiwIBhmm6qDSFwAAAGIwYAYJKoZIhvcNAQcGoFMwUQIBADBMBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDI+LoLdvYv8l41OhAAIBEIAfx49FFJCLeYrkfMfAw6XlnxP23MmDBdqP8dPp28OoAQ=="
+    # ... Use same algorithm used to Encrypt the payload ...
+    encryption_algorithm = "RSAES_OAEP_SHA_256"
+    key_id               = "ab123456-c012-4567-890a-deadbeef123"
+  }
+}
+```
+
+## Argument Reference
+
+This data source supports the following arguments:
+
+* `secret` - (Required) One or more encrypted payload definitions from the KMS service. See the Secret Definitions below.
+
+### Secret Definitions
+
+Each `secret` supports the following arguments:
+
+* `name` - (Required) Name to export this secret under in the attributes.
+* `payload` - (Required) Base64 encoded payload, as returned from a KMS encrypt operation.
+* `context` - (Optional) An optional mapping that makes up the Encryption Context for the secret.
+* `grant_tokens` (Optional) An optional list of Grant Tokens for the secret.
+* `encryption_algorithm` - (Optional) The encryption algorithm that will be used to decrypt the ciphertext. This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key. Valid Values: SYMMETRIC_DEFAULT | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256 | SM2PKE
+* `key_id` (Optional) Specifies the KMS key that AWS KMS uses to decrypt the ciphertext. This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key.
+
+For more information on `context` and `grant_tokens` see the [KMS
+Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)
+
+## Attribute Reference
+
+This ephemeral resource exports the following attributes in addition to the arguments above:
+
+* `plaintext` - Map containing each `secret` `name` as the key with its decrypted plaintext value

website/docs/ephemerals/secretsmanager_secret_version.html.markdown

@@ -0,0 +1,59 @@
+---
+subcategory: "Secrets Manager"
+layout: "aws"
+page_title: "AWS: aws_secretsmanager_secret_version"
+description: |-
+  Retrieve information about a Secrets Manager secret version including its secret value
+---
+
+# Ephemeral: aws_secretsmanager_secret_version
+
+Retrieve information about a Secrets Manager secret version, including its secret value. To retrieve secret metadata, see the [`aws_secretsmanager_secret` data source](/docs/providers/aws/d/secretsmanager_secret.html).
+
+## Example Usage
+
+### Retrieve Current Secret Version
+
+By default, this ephemeral resource retrieves information based on the `AWSCURRENT` staging label.
+
+```terraform
+ephemeral "aws_secretsmanager_secret_version" "example" {
+  secret_id = data.aws_secretsmanager_secret.example.id
+}
+```
+
+### Retrieve Specific Secret Version
+
+```terraform
+ephemeral "aws_secretsmanager_secret_version" "by-version-stage" {
+  secret_id     = data.aws_secretsmanager_secret.example.id
+  version_stage = "example"
+}
+```
+
+### Handling Key-Value Secret Strings in JSON
+
+Reading key-value pairs from JSON back into a native Terraform map can be accomplished in Terraform 0.12 and later with the [`jsondecode()` function](https://www.terraform.io/docs/configuration/functions/jsondecode.html):
+
+```terraform
+output "example" {
+  value = ephemeral.aws_secretsmanager_secret_version.example.secret_string["key1"]
+}
+```
+
+## Argument Reference
+
+* `secret_id` - (Required) Specifies the secret containing the version that you want to retrieve. You can specify either the ARN or the friendly name of the secret.
+* `version_id` - (Optional) Specifies the unique identifier of the version of the secret that you want to retrieve. Overrides `version_stage`.
+* `version_stage` - (Optional) Specifies the secret version that you want to retrieve by the staging label attached to the version. Defaults to `AWSCURRENT`.
+
+## Attribute Reference
+
+This ephemeral resource exports the following attributes in addition to the arguments above:
+
+* `arn` - ARN of the secret.
+* `created_date` - Created date of the secret in UTC.
+* `id` - Unique identifier of this version of the secret.
+* `secret_string` - Decrypted part of the protected secret information that was originally provided as a string.
+* `secret_binary` - Decrypted part of the protected secret information that was originally provided as a binary.
+* `version_id` - Unique identifier of this version of the secret.