Provider configuration

A provider is one cloud account, project or subscription, in one region, with one set of credentials. Register as many as you need, each under its own name.

ProviderConfig#

ProviderConfig aws = ProviderConfig.of("aws")              // aws | azure | gcp | vault | memory
        .region("eu-west-2")                              // optional: the cloud's default otherwise
        .endpoint(URI.create("http://localhost:4566"))    // optional: an emulator or compatible service
        .credentials(Credentials.defaultChain())          // the default
        .property("http.max-connections", "256");         // provider settings, below

Halyx halyx = Halyx.builder().register("orders", aws).build();

In Spring Boot, the same settings live under halyx.providers.<name>; see Spring Boot.

A blank property value is no value, here and in every resource config's property(...): it removes the setting. So an optional setting can come from an environment variable that some deployments leave unset, as in gcp.sql.instance: ${ORDERS_SQL_INSTANCE:}, and it never reaches a driver as an empty file path or instance name.

Credentials#

Prefer the default chain. It covers workload identity on Kubernetes, managed identities and CLI logins, with no secrets in configuration. Passwordless database, cache and Kafka logins (SQL, caches, streams) need an identity: on Azure the default chain or a service principal, on Google Cloud the default chain or impersonation.

Assumed roles and impersonated service accounts#

Credentials.impersonate(target) acts as another identity, with temporary credentials that are refreshed before they expire. It starts from the default chain:

// AWS: an IAM role in another account, through STS
Credentials orders = Credentials.impersonate("arn:aws:iam::123456789012:role/orders")
        .externalId("acme")                  // when the role's trust policy requires one
        .sessionName("billing")              // shown in CloudTrail; "halyx" otherwise
        .lifetime(Duration.ofMinutes(30));   // the role's default otherwise

// Google Cloud: a service account, through the IAM Credentials API
Credentials reports = Credentials.impersonate("reports@acme-prod.iam.gserviceaccount.com");

On AWS, .from(Credentials.of(accessKeyId, secret)) starts from an access key instead. The identity the provider starts from needs permission to act as the target: sts:AssumeRole in the role's trust policy on AWS, or roles/iam.serviceAccountTokenCreator on the service account on Google Cloud. A session name and an external ID are AWS settings, and Google Cloud refuses them.

Register one provider per account or role. Each gets its own credentials, so one application can use buckets in several AWS accounts, each through its own role.

Entra ID service principals#

Code running outside Azure, on AWS, on Google Cloud or on premises, has no managed identity, so it logs in to Azure as a Microsoft Entra ID application (a service principal):

Credentials.servicePrincipal(tenantId, clientId, clientSecret);
Credentials.servicePrincipalWithCertificate(tenantId, clientId, Path.of("/etc/halyx/app.pem"));   // certificate and private key
Credentials.servicePrincipalWithFederatedToken(tenantId, clientId, Path.of("/var/run/secrets/azure/token"));

A federated token needs no stored secret. Entra ID trusts the token's issuer through a federated identity credential on the application, so a pod on EKS or GKE can log in to Azure with the Kubernetes service account token its cluster projects into it. Every Azure service uses the service principal, including Entra ID logins to databases, caches and Event Hubs.

HTTP connections#

Each provider connection shares one pooled HTTP client across its services: S3, SSM, Secrets Manager and Lambda on AWS; Blob Storage, Key Vault, App Configuration and Azure Functions on Azure; Cloud Storage and Cloud Run functions on Google Cloud.

Durations take 500ms, 30s or 5m style values, or ISO-8601 (PT30S). AWS uses the Apache 5 client and Azure its default Netty client. Cloud Storage uses an Apache transport instead of the JDK's HttpURLConnection, which keeps only 5 idle connections. Google's gRPC clients (Pub/Sub, Firestore, Secret Manager, Parameter Manager) multiplex over HTTP/2 and aren't affected.

Upload part buffers come from a JVM-wide pool. Set the most it keeps idle with the system property halyx.buffer-pool.max-bytes (256 MiB by default).

AWS#

ProviderConfig.of("aws").region("eu-west-2")

Settings marked with a config type are set on that config (for example TableConfig.builder(...).property(...)) rather than on the provider.

Azure#

ProviderConfig.of("azure")
        .property(AzureProperties.STORAGE_ACCOUNT, "acmefiles")
        .property(AzureProperties.SERVICE_BUS_NAMESPACE, "acme.servicebus.windows.net")
        .property(AzureProperties.COSMOS_ENDPOINT, "https://acme.documents.azure.com:443/")
        .property(AzureProperties.COSMOS_DATABASE, "orders")

Key Vault and App Configuration take their URL as the store's location; see Parameters and secrets.

Keys that rotate can be given as suppliers, such as a read from a parameter store, and Halyx follows the rotation without a restart:

ParameterStore secrets = ...;   // with a cacheTtl, so the refreshes are cheap
ProviderConfig.of("azure")
        .property(AzureProperties.COSMOS_ENDPOINT, "https://acme.documents.azure.com:443/")
        .property(AzureProperties.COSMOS_KEY, () -> secrets.require("orders-cosmos-key"))

A failed refresh keeps the current key and is tried again at the next interval. Each of these services keeps two keys, so a rotation that switches to the other key, updates the secret, and regenerates the old key after the refresh interval plus the store's cache TTL fails no requests.

Google Cloud#

ProviderConfig.of("gcp").property(GcpProperties.PROJECT_ID, "acme-prod")

HashiCorp Vault#

ProviderConfig.of("vault")
        .endpoint(URI.create("https://vault.internal:8200"))
        .property("vault.auth", "kubernetes")
        .property("vault.kubernetes.role", "orders-svc")

The KV v2 mount is the parameter store's location (secret by default).

In-memory#

ProviderConfig.of("memory")

No settings. Object storage, NoSQL, messaging, events, streams, functions, caches, and parameters and secrets live in the JVM; functions are handlers registered with InMemoryFunctions. It's ideal for unit tests.