Production Configuration Best Practices

A pre-launch checklist for AWS SDK authentication and configuration hygiene.

Walk it before a service goes live, and revisit it whenever you add a new environment or credential source.

How to Use This Checklist

Walk the groups top-down: credentials and identity first, then configuration, then observability.
Treat each - [ ] as a gate - do not launch with an unchecked security item.
Record where each setting comes from (code, env, profile, role) so precedence is auditable.
Re-run it per environment - laptop, CI, staging, and production resolve credentials differently.
The earliest groups are the least reversible; a leaked long-lived key outlives a wrong timeout.

A - Credentials & Identity

Use roles and temporary credentials, not long-lived keys. Attach an instance/task role or use IRSA so no static secret exists in the workload.
Never hardcode access keys in source or container images. Keys in code or a baked image leak through version control and registries.
Let the default chain resolve credentials. Pin a single provider only when one environment truly requires it.
Give every AssumeRole call a descriptive RoleSessionName. It is the CloudTrail attribution for the whole session.
Require an ExternalId for third-party role assumption. It closes the confused-deputy hole when a vendor assumes a role in your account.
Rely on auto-refresh for temporary credentials. Use a profile or fromTemporaryCredentials/fromWebToken rather than a one-shot manual assume.

B - Metadata & Compute Hardening

Enforce IMDSv2 (http-tokens required). The v2 PUT-token handshake blocks the SSRF attacks that stole v1 credentials.
Set the IMDS hop limit correctly. Use at least 2 when containers on the instance need metadata credentials.
Set AWS_EC2_METADATA_V1_DISABLED=true. Make the SDK itself refuse the legacy v1 path.
Keep node/instance roles minimal. A broad node role masks missing per-workload IRSA and widens blast radius.
Bound the IMDS timeout and retries. A blocked 169.254.169.254 should fail fast, not hang startup.

C - Configuration

Set region explicitly. There is no default region; pin it in code or env for every client.
Configure retries deliberately. Choose standard or adaptive mode and a max-attempts value rather than accepting defaults.
Set connect and read timeouts. Stop a stuck socket from blocking a worker indefinitely.
Create one client per service and reuse it. Clients are thread-safe and pool connections; re-creating them adds latency.
Centralize config in one factory. A single shared config object prevents drift between clients.
Know your precedence order. Code beats env beats profile beats default - avoid stray AWS_REGION/AWS_PROFILE surprises.

D - Least Privilege & Secrets

Scope each role to least privilege. Grant only the actions and resources the workload uses.
Give custom-provider bootstrap identities minimal rights. A Secrets Manager fetch should read exactly one secret.
Return an expiration from custom providers. Without it, rotated credentials silently go stale.
Prefer built-in providers over hand-rolled ones. Use credential_process/fromProcess, fromWebToken, and fromTemporaryCredentials before writing custom code.
Never disable TLS verification. Keep certificate verification on for every client.

E - Observability & Verification

Log the resolved identity at startup. A boot-time get_caller_identity turns wrong-account bugs into an obvious log line.
Fail fast on missing credentials. Catch NoCredentialsError/CredentialsProviderError at startup with an actionable message.
Log the request id on errors. Record RequestId/$metadata.requestId for support cases and tracing.
Verify each environment resolves the expected source. Confirm CI, staging, and prod each pick the intended link in the chain.

When You Are Done

Every Group A and B item is checked - these are the security-critical, least-reversible ones.
Region, retries, and timeouts are explicit for every client.
Startup logs show the correct identity and account in each environment.

FAQs

Why are credentials the first group?

They are the highest-leverage and least reversible. A leaked long-lived key can be abused long after a wrong timeout would have been noticed and fixed.

Can I skip roles and just use env-var keys?

For local dev, env vars are fine. For production compute, prefer an attached role so no static secret lives in the workload at all.

Why enforce IMDSv2 specifically?

Its required PUT-token handshake blocks the server-side request forgery attacks that let attackers read v1 credentials with a simple GET.

What hop limit should I use?

Default 1 blocks containers on the instance. Set at least 2 when containerized apps on EC2 need metadata credentials.

Why set region explicitly when a profile has one?

There is no built-in default region, and env vars can override the profile. Pinning region in code removes ambiguity for regional services.

Is adaptive retry mode always better?

Not always. Standard is a solid default; adaptive adds client-side rate limiting that helps under sustained throttling but is unnecessary for low-volume calls.

When can I skip the ExternalId item?

When no external party assumes roles in your account. It is essential specifically for third-party, cross-organization role assumption.

Why log identity at startup?

Precedence and chain bugs are invisible until observed. A one-line get_caller_identity at boot surfaces wrong-account misconfiguration immediately.

What is the top mistake this checklist prevents?

Shipping long-lived keys - in code, an image, or a stray env var - instead of using roles and temporary, auto-refreshed credentials.

Do I need a custom provider expiration if keys never rotate?

If keys are truly static you can omit it, but returning an expiration is safer and required the moment rotation is introduced.

Should I reuse clients in serverless?

Yes. Construct clients outside the handler so warm invocations reuse the connection pool and resolved credentials.

How often should I re-run this checklist?

Before launch, and again whenever you add an environment, a credential source, or a new cross-account or third-party integration.

Production SDK Configuration Basics - the settings behind Group C.
The Credential Provider Chain, End to End - the resolution order Group A relies on.
Instance Metadata Service (IMDSv2) for EC2 Credentials - the details behind Group B.
SDK Config Precedence: Env, Profile, Code & Defaults - the precedence item in Group C.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Production Configuration Best Practices

A pre-launch checklist for AWS SDK authentication and configuration hygiene.

Walk it before a service goes live, and revisit it whenever you add a new environment or credential source.

How to Use This Checklist

Walk the groups top-down: credentials and identity first, then configuration, then observability.
Treat each - [ ] as a gate - do not launch with an unchecked security item.
Record where each setting comes from (code, env, profile, role) so precedence is auditable.
Re-run it per environment - laptop, CI, staging, and production resolve credentials differently.
The earliest groups are the least reversible; a leaked long-lived key outlives a wrong timeout.

A - Credentials & Identity

Use roles and temporary credentials, not long-lived keys. Attach an instance/task role or use IRSA so no static secret exists in the workload.
Never hardcode access keys in source or container images. Keys in code or a baked image leak through version control and registries.
Let the default chain resolve credentials. Pin a single provider only when one environment truly requires it.
Give every AssumeRole call a descriptive RoleSessionName. It is the CloudTrail attribution for the whole session.
Require an ExternalId for third-party role assumption. It closes the confused-deputy hole when a vendor assumes a role in your account.
Rely on auto-refresh for temporary credentials. Use a profile or fromTemporaryCredentials/fromWebToken rather than a one-shot manual assume.

B - Metadata & Compute Hardening

Enforce IMDSv2 (http-tokens required). The v2 PUT-token handshake blocks the SSRF attacks that stole v1 credentials.
Set the IMDS hop limit correctly. Use at least 2 when containers on the instance need metadata credentials.
Set AWS_EC2_METADATA_V1_DISABLED=true. Make the SDK itself refuse the legacy v1 path.
Keep node/instance roles minimal. A broad node role masks missing per-workload IRSA and widens blast radius.
Bound the IMDS timeout and retries. A blocked 169.254.169.254 should fail fast, not hang startup.

C - Configuration

Set region explicitly. There is no default region; pin it in code or env for every client.
Configure retries deliberately. Choose standard or adaptive mode and a max-attempts value rather than accepting defaults.
Set connect and read timeouts. Stop a stuck socket from blocking a worker indefinitely.
Create one client per service and reuse it. Clients are thread-safe and pool connections; re-creating them adds latency.
Centralize config in one factory. A single shared config object prevents drift between clients.
Know your precedence order. Code beats env beats profile beats default - avoid stray AWS_REGION/AWS_PROFILE surprises.

D - Least Privilege & Secrets

Scope each role to least privilege. Grant only the actions and resources the workload uses.
Give custom-provider bootstrap identities minimal rights. A Secrets Manager fetch should read exactly one secret.
Return an expiration from custom providers. Without it, rotated credentials silently go stale.
Prefer built-in providers over hand-rolled ones. Use credential_process/fromProcess, fromWebToken, and fromTemporaryCredentials before writing custom code.
Never disable TLS verification. Keep certificate verification on for every client.

E - Observability & Verification

Log the resolved identity at startup. A boot-time get_caller_identity turns wrong-account bugs into an obvious log line.
Fail fast on missing credentials. Catch NoCredentialsError/CredentialsProviderError at startup with an actionable message.
Log the request id on errors. Record RequestId/$metadata.requestId for support cases and tracing.
Verify each environment resolves the expected source. Confirm CI, staging, and prod each pick the intended link in the chain.

When You Are Done

Every Group A and B item is checked - these are the security-critical, least-reversible ones.
Region, retries, and timeouts are explicit for every client.
Startup logs show the correct identity and account in each environment.

FAQs

Why are credentials the first group?

They are the highest-leverage and least reversible. A leaked long-lived key can be abused long after a wrong timeout would have been noticed and fixed.

Can I skip roles and just use env-var keys?

For local dev, env vars are fine. For production compute, prefer an attached role so no static secret lives in the workload at all.

Why enforce IMDSv2 specifically?

Its required PUT-token handshake blocks the server-side request forgery attacks that let attackers read v1 credentials with a simple GET.

What hop limit should I use?

Default 1 blocks containers on the instance. Set at least 2 when containerized apps on EC2 need metadata credentials.

Why set region explicitly when a profile has one?

There is no built-in default region, and env vars can override the profile. Pinning region in code removes ambiguity for regional services.

Is adaptive retry mode always better?

Not always. Standard is a solid default; adaptive adds client-side rate limiting that helps under sustained throttling but is unnecessary for low-volume calls.

When can I skip the ExternalId item?

When no external party assumes roles in your account. It is essential specifically for third-party, cross-organization role assumption.

Why log identity at startup?

Precedence and chain bugs are invisible until observed. A one-line get_caller_identity at boot surfaces wrong-account misconfiguration immediately.

What is the top mistake this checklist prevents?

Shipping long-lived keys - in code, an image, or a stray env var - instead of using roles and temporary, auto-refreshed credentials.

Do I need a custom provider expiration if keys never rotate?

If keys are truly static you can omit it, but returning an expiration is safer and required the moment rotation is introduced.

Should I reuse clients in serverless?

Yes. Construct clients outside the handler so warm invocations reuse the connection pool and resolved credentials.

How often should I re-run this checklist?

Before launch, and again whenever you add an environment, a credential source, or a new cross-account or third-party integration.

Production SDK Configuration Basics - the settings behind Group C.
The Credential Provider Chain, End to End - the resolution order Group A relies on.
Instance Metadata Service (IMDSv2) for EC2 Credentials - the details behind Group B.
SDK Config Precedence: Env, Profile, Code & Defaults - the precedence item in Group C.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Production Configuration Best Practices

Buscar na documentação

Production Configuration Best Practices