Production SDK Configuration Basics

Nine examples to get you started with production-ready SDK configuration - six basic and three intermediate.

The SDK defaults are tuned for getting started, not for a service under load. Before you ship, make region, credentials, retries, and timeouts explicit so behavior is predictable across every environment.

Prerequisites

Python: pip install boto3 (1.43.x, Python 3.10+).
Node: npm install @aws-sdk/client-sts @aws-sdk/credential-providers (SDK v3, Node 18+). Install only the @aws-sdk/client-* packages you use.
Working credentials reachable by the default provider chain (a profile, env vars, or an instance role).

Basic Examples

1. Always Set the Region Explicitly

Never rely on the ambient default region in production code.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
print(s3.meta.region_name)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
console.log(await s3.config.region());

An unset region falls back to env or profile config, which differs per machine.
A wrong region silently talks to the wrong endpoint or fails to resolve one.
Pass region_name / region at client construction, not per call.

Related: SDK Config Precedence: Env, Profile, Code & Defaults - where region is resolved from.

2. Create One Client and Reuse It

Clients are thread-safe and pool TCP connections, so construct them once.

# --- Python (boto3) ---
import boto3
 
# Module-level: created once, reused across requests.
DDB = boto3.client("dynamodb", region_name="us-east-1")
 
def get_item(key):
    return DDB.get_item(TableName="orders", Key=key)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
 
// Module scope: created once, reused across requests.
const ddb = new DynamoDBClient({ region: "us-east-1" });
 
export const getItem = (Key: Record<string, any>) =>
  ddb.send(new GetItemCommand({ TableName: "orders", Key }));

Re-creating a client per request throws away the connection pool and adds latency.
A shared client amortizes credential resolution and endpoint setup.
In serverless, construct clients outside the handler so warm invocations reuse them.

3. Configure Retries Deliberately

Pick a retry mode and a max attempt count instead of accepting the default.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(retries={"max_attempts": 5, "mode": "adaptive"})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { AdaptiveRetryStrategy } from "@smithy/util-retry";
 
const s3 = new S3Client({
  region: "us-east-1",
  maxAttempts: 5,
  retryStrategy: new AdaptiveRetryStrategy(async () => 5),
});

adaptive mode adds client-side rate limiting on throttling responses.
max_attempts counts the initial try plus retries.
Standard mode is a fine default; adaptive helps under sustained throttling.

4. Set Connect and Read Timeouts

Bound how long a single request can hang so a stuck socket cannot stall your service.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(connect_timeout=3, read_timeout=10, retries={"max_attempts": 3})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
 
const s3 = new S3Client({
  region: "us-east-1",
  requestHandler: new NodeHttpHandler({ connectionTimeout: 3000, requestTimeout: 10000 }),
});

boto3 timeouts are in seconds; SDK v3 timeouts are in milliseconds.
Without timeouts a network stall can block a worker indefinitely.
Keep the read timeout above your slowest expected legitimate response.

5. Pin the Credential Source Per Environment

Be explicit about where credentials come from rather than trusting the ambient chain.

# --- Python (boto3) ---
import boto3
 
# Local/dev: a named profile from the shared config files.
session = boto3.Session(profile_name="payments-dev")
s3 = session.client("s3", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";
 
// Local/dev: a named profile from the shared config files.
const s3 = new S3Client({ region: "us-east-1", credentials: fromIni({ profile: "payments-dev" }) });

In production containers or EC2, drop the explicit profile and let the role-based chain answer.
Pinning the source removes ambiguity about which identity a run used.
Never hardcode access keys in code - use a profile, env vars, or a role.

Related: The Credential Provider Chain, End to End - what the chain resolves when you do not pin a source.

6. Verify the Resolved Identity at Startup

Log who you are before serving traffic so misconfiguration fails loudly.

# --- Python (boto3) ---
import boto3
 
ident = boto3.client("sts", region_name="us-east-1").get_caller_identity()
print("Running as", ident["Arn"], "in account", ident["Account"])

// --- TypeScript (AWS SDK v3) ---
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
 
const id = await new STSClient({ region: "us-east-1" }).send(new GetCallerIdentityCommand({}));
console.log("Running as", id.Arn, "in account", id.Account);

Turns a silent "wrong account" bug into an obvious log line at boot.
get_caller_identity needs no special permission and never throttles in practice.
Emit the ARN and account id to your logs, not just the console.

Intermediate Examples

7. Centralize Config in One Factory

Build every client through a single helper so retries, timeouts, and region stay consistent.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
_CFG = Config(
    region_name="us-east-1",
    retries={"max_attempts": 5, "mode": "adaptive"},
    connect_timeout=3,
    read_timeout=10,
)
 
def client(service: str):
    return boto3.client(service, config=_CFG)
 
s3, ddb = client("s3"), client("dynamodb")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
 
const shared = {
  region: "us-east-1",
  maxAttempts: 5,
  requestHandler: new NodeHttpHandler({ connectionTimeout: 3000, requestTimeout: 10000 }),
};
 
export const s3 = new S3Client(shared);
export const ddb = new DynamoDBClient(shared);

One config object means one place to tune production behavior.
boto3 accepts region_name inside Config, so a single object covers region too.
Avoids drift where one client retries five times and another retries three.

8. Turn On Standard Endpoint and TLS Hygiene

Prefer regional endpoints and never disable certificate verification.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(
    region_name="us-east-1",
    s3={"addressing_style": "virtual"},
    # verify defaults to True - never set verify=False in production.
)
s3 = boto3.client("s3", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({
  region: "us-east-1",
  forcePathStyle: false, // prefer virtual-hosted-style endpoints
  // TLS verification is on by default - do not disable it.
});

Virtual-hosted-style S3 addressing is the modern default; path style is legacy.
Disabling TLS verification exposes traffic to interception - keep it on.
Override endpoints only for local emulators like LocalStack, never in production.

9. Fail Fast When Credentials Are Missing

Catch the no-credentials case at startup with a clear, actionable error.

# --- Python (boto3) ---
import boto3
from botocore.exceptions import NoCredentialsError
 
try:
    boto3.client("sts", region_name="us-east-1").get_caller_identity()
except NoCredentialsError:
    raise SystemExit("No AWS credentials resolved - check profile, env, or role.")

// --- TypeScript (AWS SDK v3) ---
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
import { CredentialsProviderError } from "@smithy/property-provider";
 
try {
  await new STSClient({ region: "us-east-1" }).send(new GetCallerIdentityCommand({}));
} catch (e) {
  if (e instanceof CredentialsProviderError)
    throw new Error("No AWS credentials resolved - check profile, env, or role.");
  throw e;
}

A startup probe surfaces auth problems before the first user request does.
boto3 raises NoCredentialsError; SDK v3 raises CredentialsProviderError.
Convert the raw error into a message that names the sources you expected.

Related: Production Configuration Best Practices - the full pre-launch checklist.

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

Prerequisites

Python: pip install boto3 (1.43.x, Python 3.10+).
Node: npm install @aws-sdk/client-sts @aws-sdk/credential-providers (SDK v3, Node 18+). Install only the @aws-sdk/client-* packages you use.
Working credentials reachable by the default provider chain (a profile, env vars, or an instance role).

Basic Examples

1. Always Set the Region Explicitly

Never rely on the ambient default region in production code.

# --- Python (boto3) ---
import boto3
 
s3 = boto3.client("s3", region_name="us-east-1")
print(s3.meta.region_name)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
console.log(await s3.config.region());

An unset region falls back to env or profile config, which differs per machine.
A wrong region silently talks to the wrong endpoint or fails to resolve one.
Pass region_name / region at client construction, not per call.

Related: SDK Config Precedence: Env, Profile, Code & Defaults - where region is resolved from.

2. Create One Client and Reuse It

Clients are thread-safe and pool TCP connections, so construct them once.

# --- Python (boto3) ---
import boto3
 
# Module-level: created once, reused across requests.
DDB = boto3.client("dynamodb", region_name="us-east-1")
 
def get_item(key):
    return DDB.get_item(TableName="orders", Key=key)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
 
// Module scope: created once, reused across requests.
const ddb = new DynamoDBClient({ region: "us-east-1" });
 
export const getItem = (Key: Record<string, any>) =>
  ddb.send(new GetItemCommand({ TableName: "orders", Key }));

Re-creating a client per request throws away the connection pool and adds latency.
A shared client amortizes credential resolution and endpoint setup.
In serverless, construct clients outside the handler so warm invocations reuse them.

3. Configure Retries Deliberately

Pick a retry mode and a max attempt count instead of accepting the default.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(retries={"max_attempts": 5, "mode": "adaptive"})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { AdaptiveRetryStrategy } from "@smithy/util-retry";
 
const s3 = new S3Client({
  region: "us-east-1",
  maxAttempts: 5,
  retryStrategy: new AdaptiveRetryStrategy(async () => 5),
});

adaptive mode adds client-side rate limiting on throttling responses.
max_attempts counts the initial try plus retries.
Standard mode is a fine default; adaptive helps under sustained throttling.

4. Set Connect and Read Timeouts

Bound how long a single request can hang so a stuck socket cannot stall your service.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(connect_timeout=3, read_timeout=10, retries={"max_attempts": 3})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
 
const s3 = new S3Client({
  region: "us-east-1",
  requestHandler: new NodeHttpHandler({ connectionTimeout: 3000, requestTimeout: 10000 }),
});

boto3 timeouts are in seconds; SDK v3 timeouts are in milliseconds.
Without timeouts a network stall can block a worker indefinitely.
Keep the read timeout above your slowest expected legitimate response.

5. Pin the Credential Source Per Environment

Be explicit about where credentials come from rather than trusting the ambient chain.

# --- Python (boto3) ---
import boto3
 
# Local/dev: a named profile from the shared config files.
session = boto3.Session(profile_name="payments-dev")
s3 = session.client("s3", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";
 
// Local/dev: a named profile from the shared config files.
const s3 = new S3Client({ region: "us-east-1", credentials: fromIni({ profile: "payments-dev" }) });

In production containers or EC2, drop the explicit profile and let the role-based chain answer.
Pinning the source removes ambiguity about which identity a run used.
Never hardcode access keys in code - use a profile, env vars, or a role.

Related: The Credential Provider Chain, End to End - what the chain resolves when you do not pin a source.

6. Verify the Resolved Identity at Startup

Log who you are before serving traffic so misconfiguration fails loudly.

# --- Python (boto3) ---
import boto3
 
ident = boto3.client("sts", region_name="us-east-1").get_caller_identity()
print("Running as", ident["Arn"], "in account", ident["Account"])

// --- TypeScript (AWS SDK v3) ---
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
 
const id = await new STSClient({ region: "us-east-1" }).send(new GetCallerIdentityCommand({}));
console.log("Running as", id.Arn, "in account", id.Account);

Turns a silent "wrong account" bug into an obvious log line at boot.
get_caller_identity needs no special permission and never throttles in practice.
Emit the ARN and account id to your logs, not just the console.

Intermediate Examples

7. Centralize Config in One Factory

Build every client through a single helper so retries, timeouts, and region stay consistent.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
_CFG = Config(
    region_name="us-east-1",
    retries={"max_attempts": 5, "mode": "adaptive"},
    connect_timeout=3,
    read_timeout=10,
)
 
def client(service: str):
    return boto3.client(service, config=_CFG)
 
s3, ddb = client("s3"), client("dynamodb")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
 
const shared = {
  region: "us-east-1",
  maxAttempts: 5,
  requestHandler: new NodeHttpHandler({ connectionTimeout: 3000, requestTimeout: 10000 }),
};
 
export const s3 = new S3Client(shared);
export const ddb = new DynamoDBClient(shared);

One config object means one place to tune production behavior.
boto3 accepts region_name inside Config, so a single object covers region too.
Avoids drift where one client retries five times and another retries three.

8. Turn On Standard Endpoint and TLS Hygiene

Prefer regional endpoints and never disable certificate verification.

# --- Python (boto3) ---
import boto3
from botocore.config import Config
 
cfg = Config(
    region_name="us-east-1",
    s3={"addressing_style": "virtual"},
    # verify defaults to True - never set verify=False in production.
)
s3 = boto3.client("s3", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({
  region: "us-east-1",
  forcePathStyle: false, // prefer virtual-hosted-style endpoints
  // TLS verification is on by default - do not disable it.
});

Virtual-hosted-style S3 addressing is the modern default; path style is legacy.
Disabling TLS verification exposes traffic to interception - keep it on.
Override endpoints only for local emulators like LocalStack, never in production.

9. Fail Fast When Credentials Are Missing

Catch the no-credentials case at startup with a clear, actionable error.

# --- Python (boto3) ---
import boto3
from botocore.exceptions import NoCredentialsError
 
try:
    boto3.client("sts", region_name="us-east-1").get_caller_identity()
except NoCredentialsError:
    raise SystemExit("No AWS credentials resolved - check profile, env, or role.")

// --- TypeScript (AWS SDK v3) ---
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
import { CredentialsProviderError } from "@smithy/property-provider";
 
try {
  await new STSClient({ region: "us-east-1" }).send(new GetCallerIdentityCommand({}));
} catch (e) {
  if (e instanceof CredentialsProviderError)
    throw new Error("No AWS credentials resolved - check profile, env, or role.");
  throw e;
}

A startup probe surfaces auth problems before the first user request does.
boto3 raises NoCredentialsError; SDK v3 raises CredentialsProviderError.
Convert the raw error into a message that names the sources you expected.

Related: Production Configuration Best Practices - the full pre-launch checklist.

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 SDK Configuration Basics

Buscar na documentação

Production SDK Configuration Basics