Create a StaticRegionProvider

[cloudshiftchris]

Describe the feature

Create a StaticRegionProvider class to explicitly set a region to use.

Is your Feature Request related to a problem?

Currently Kotlin SDK does not have a mechanism to explicitly set the region via a RegionProvider; this is useful for say development environments (outside of AWS) where the region can't be directly inferred and configuration is integrated with other application configuration (i.e. no using system properties or environment variables)

Proposed Solution

public class StaticRegionProvider(private val region: String) : RegionProvider {
    override suspend fun getRegion(): String = region
}

Describe alternative solutions or features you've considered

See proposed solution.

Acknowledge

• I may be able to implement this feature request

AWS Kotlin SDK version used

029.0-beta

Platform (JVM/JS/Native)

JVM

Operating System and version

MacOS

[aajtodd]

Is this just a "nice to have" request or is this blocking something for you?

As far as I understand the request you can get this now by wrapping client creation in a way that you consult your own region provider and pass that to client construction.

e.g.

val resolvedRegion = regionProvider.getRegion()
val s3 = S3Client.fromEnvironment{
    region = resolvedRegion
}

[cloudshiftchris]

Not blocking anything atm, have done as noted above, creating our own StaticRegionProvider driven by configuration.

Q: what are RegionProviders used for in Kotlin SDK? They aren't symmetrical with CredentialsProvider behaviour (provider set at construction time, queried for each API call). Kotlin SDK clients look to use a stringly-typed region parameter at construction time.

[aajtodd]

Q: what are RegionProviders used for in Kotlin SDK? They aren't symmetrical with CredentialsProvider behaviour (provider set at construction time, queried for each API call). Kotlin SDK clients look to use a stringly-typed region parameter at construction time.

They're used in fromEnvironment when we need to try and auto detect the region that the client should be configured for. Unlike credentials, region is static once set and doesn't change through the lifetime of a client (e.g. region doesn't expire, your EC2 instance isn't going to magically be in a different region, etc). If you need to talk to a different region you would create a new client or use the withConfig extension (see developer guide here).

[RanVaknin]

Hi @cloudshiftchris,

After reviewing this thread with the team, we need more clarification about your use case.

Since region is static and can be directly set during client construction (e.g. region = "us-east-1"), could you explain why a StaticRegionProvider would be necessary? What specific scenario requires this that can't be handled by the current region parameter?

This would help us better understand if there's a gap in functionality that needs to be addressed.

Thanks.
Ran~

[cloudshiftchris]

@RanVaknin this came from some configuration code we have to create/configure SDK clients; for the region stuff one can specify where (in order) to pull the region from:

    public data class RegionProperties(
        val static: String? = null,
        val environment: Boolean = true,
        val jvmSystemProperty: Boolean = false,
        val imds: Boolean = true,
        val profile: String? = null,
    )

...that is then used in this code snippet to create a List<RegionProvider> to resolve regions.

internal fun AwsClientProperties.RegionProperties.toRegionProviderList(): List<RegionProvider> {
    return listOfNotNull(
        static?.let { StaticRegionProvider(it) },
        imds.takeIf { it }?.let { ImdsRegionProvider() },
        environment.takeIf { it }?.let { EnvironmentRegionProvider() },
        jvmSystemProperty.takeIf { it }?.let { JvmSystemPropertyRegionProvider() },
        profile?.let { ProfileRegionProvider(it) },
    )
}

internal fun AwsClientProperties.RegionProperties.toRegionProvider(): RegionProvider {
    val providers = toRegionProviderList()
    require(providers.isNotEmpty()) {
        "No region providers specified; set properties to configure region providers"
    }
    return RegionProviderChain(*providers.toTypedArray())
}

...ultimately we boil this down to setting the region on SDK client creation:

 customizers.add(
            awsKotlinSdkClientCustomizer {
                awsSdkClient {
                    useDualStack = props.useDualStack
                    useFips = props.useFips
                    region = [email protected]
                }
                credentialsProvider { credentialsProvider = serviceCredentialsProvider }
            }
        )

[ianbotsf]

Thanks for the additional info @cloudshiftchris. I can see now how a StaticRegionProvider would be useful to code which deals with region sources generically. It should be fairly simple to implement this for your use case.

[cloudshiftchris]

Thanks for the additional info @cloudshiftchris. I can see now how a StaticRegionProvider would be useful to code which deals with region sources generically. It should be fairly simple to implement this for your use case.

Thanks @ianbotsf . If it helps here's our implementation:

// see https://github.com/awslabs/aws-sdk-kotlin/issues/1005
internal class StaticRegionProvider(private val region: String) : RegionProvider {
    override suspend fun getRegion(): String = region
}