luciano/amazon-kinesis-client
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite credentials doc to be consistent with v2 changes

Browse source
This commit is contained in:
Ethan Katnic 2024-09-04 10:58:50 -07:00
parent 90d984b670
commit 3923eb8bee
1 changed files with 21 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/multilang/configuring-credential-providers.md
View file

@ -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|<arn>|<sessionName>`
```
To create a [StsAssumeRoleCredentialsProvider][sts-assume-provider], see KclStsAssumeRoleCredentialsProvider below.
In a Properties file, an `AWSCredentialsProperty` configuration might look like:
```
AWSCredentialsProvider = StsAssumeRoleCredentialsProvider|<arn>|<sessionName>
```
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|<arn>|<sessionName>\
|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:
<nested-value ::= <string> # 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|<arn>|<sessionName>
[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