From 3923eb8beee4e417a182f3f95fc7cc64285a60bd Mon Sep 17 00:00:00 2001 From: Ethan Katnic Date: Wed, 4 Sep 2024 10:58:50 -0700 Subject: [PATCH] Rewrite credentials doc to be consistent with v2 changes --- .../configuring-credential-providers.md | 33 ++++++++++++------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/multilang/configuring-credential-providers.md b/docs/multilang/configuring-credential-providers.md index c8401d9e..55318d4f 100644 --- a/docs/multilang/configuring-credential-providers.md +++ b/docs/multilang/configuring-credential-providers.md @@ -7,23 +7,28 @@ However, KCL now provides better extensibility to handle, and be enhanced to han This document should help multilang customers configure a suitable `CredentialProvider` (or contribute changes to support a new use case!). ## Sample Provider Configuration -DEPRECATED: StsAssumeRoleCredentialsProvider can no longer be constructed in this way: -``` -AWSCredentialsProvider = StsAssumeRoleCredentialsProvider||` -``` -To create a [StsAssumeRoleCredentialsProvider][sts-assume-provider], see KclStsAssumeRoleCredentialsProvider below. +In a Properties file, an `AWSCredentialsProperty` configuration might look like: +``` +AWSCredentialsProvider = StsAssumeRoleCredentialsProvider|| +``` +This basic configuration creates an [StsAssumeRoleCredentialsProvider][sts-assume-provider] with an ARN and session name. -You can create a default [DefaultCredentialsProvider][default-credentials-provider] or [AnonymousCredentialsProvider][anonymous-credentials-provider] -by passing it in the config like: +While functional, this configuration is limited. +For example, this configuration cannot set a regional endpoint (e.g., VPC use case). + +Leveraging nested properties, an `AWSCredentialsProperty` value might change to: +``` +AWSCredentialsProvider = KclSTSAssumeRoleSessionCredentialsProvider||\ + |endpointRegion=us-east-1|externalId=spartacus +``` +N.B. Backslash (`\`) is for multi-line legibility and is not required. + +You can create a default [DefaultCredentialsProvider][default-credentials-provider] by passing it in the config like: ``` AWSCredentialsProvider = DefaultCredentialsProvider ``` -If you wish to customize properties on an AWS SDK provider that uses a builder, like the StsASsumeRoleCredentialsProvider, -you will need to wrap this provider class, provide a constructor, and manage the build of the provider. -See implementation of [KclStsAssumeRoleCredentialsProvider][kcl-sts-provider] - ## Nested Properties KCL multilang supports "nested properties" on the `AWSCredentialsProvider` key in the properties file. @@ -37,6 +42,10 @@ The [Backus-Naur form][bnf] of the value: # this depends on the nested key ``` +In general, required parameters are passed directly to the class' constructor or .create() method +(e.g., [ProfileCredentialsProvider(String)][profile-credentials-provider-create]). However, most of these providers +require builders and will require a custom implementation similar to `KclStsAssumeRoleCredentialsProvider` for customization + Nested properties are a custom mapping provided by KCL multilang, and do not exist in the AWS SDK. See [NestedPropertyKey][nested-property-key] for the supported keys, and details on their expected values. @@ -73,5 +82,5 @@ AWSCredentialsProvider = KclStsAssumeRoleCredentialsProvider|| [nested-property-key]: /amazon-kinesis-client-multilang/src/main/java/software/amazon/kinesis/multilang/NestedPropertyKey.java [nested-property-processor]: /amazon-kinesis-client-multilang/src/main/java/software/amazon/kinesis/multilang/NestedPropertyProcessor.java [sts-assume-provider]: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.html +[profile-credentials-provider-create]: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html#create(java.lang.String) [default-credentials-provider]: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html -[anonymous-credentials-provider]: https://sdk.amazonaws.com/java/api/2.0.0-preview-11/software/amazon/awssdk/auth/credentials/AnonymousCredentialsProvider.html