0
# Endpoint Access
1

2
Methods for obtaining service endpoints and connection details for AWS SDK client configuration, enabling seamless integration with both AWS SDK v1 and v2.
3

4
## Capabilities
5

6
### Service-Specific Endpoint Override
7

8
Get endpoint URL for a specific AWS service with automatic IP address resolution for S3 path-style access.
9

10
```java { .api }
11
/**
12
 * Provides an endpoint override preconfigured for a specific simulated service
13
 * Resolves IP address for path-style S3 access compatibility
14
 * @param service the EnabledService to get endpoint for
15
 * @return URI endpoint override for the specified service
16
 * @throws IllegalStateException if endpoint cannot be obtained
17
 */
18
public URI getEndpointOverride(EnabledService service);
19

20
/**
21
 * Legacy method for Service enum compatibility
22
 * @param service the Service enum value
23
 * @return URI endpoint override for the specified service
24
 */
25
public URI getEndpointOverride(Service service);
26
```
27

28
**Usage Examples:**
29

30
```java
31
import org.testcontainers.containers.localstack.LocalStackContainer;
32
import org.testcontainers.containers.localstack.LocalStackContainer.Service;
33

34
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
35
    .withServices(Service.S3, Service.SQS, Service.LAMBDA);
36

37
// Get service-specific endpoints
38
URI s3Endpoint = localstack.getEndpointOverride(Service.S3);
39
URI sqsEndpoint = localstack.getEndpointOverride(Service.SQS);  
40
URI lambdaEndpoint = localstack.getEndpointOverride(Service.LAMBDA);
41

42
// Use with AWS SDK v1
43
AmazonS3 s3Client = AmazonS3ClientBuilder
44
    .standard()
45
    .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
46
        s3Endpoint.toString(),
47
        localstack.getRegion()
48
    ))
49
    .withCredentials(new AWSStaticCredentialsProvider(
50
        new BasicAWSCredentials(localstack.getAccessKey(), localstack.getSecretKey())
51
    ))
52
    .build();
53

54
// Use with AWS SDK v2
55
S3Client s3ClientV2 = S3Client.builder()
56
    .endpointOverride(s3Endpoint)
57
    .credentialsProvider(StaticCredentialsProvider.create(
58
        AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
59
    ))
60
    .region(Region.of(localstack.getRegion()))
61
    .build();
62
```
63

64
### Main Endpoint Access
65

66
Get the main LocalStack endpoint URL for general service access.
67

68
```java { .api }
69
/**
70
 * Provides the main LocalStack endpoint URL
71
 * Resolves IP address for S3 path-style access compatibility
72
 * @return URI endpoint for LocalStack main port (4566)
73
 * @throws IllegalStateException if endpoint cannot be obtained
74
 */
75
public URI getEndpoint();
76
```
77

78
**Usage Examples:**
79

80
```java
81
// Get main endpoint (useful for modern LocalStack versions using single port)
82
URI mainEndpoint = localstack.getEndpoint();
83

84
// Use for multiple services via main endpoint
85
S3Client s3 = S3Client.builder()
86
    .endpointOverride(mainEndpoint)
87
    .credentialsProvider(StaticCredentialsProvider.create(
88
        AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
89
    ))
90
    .region(Region.of(localstack.getRegion()))
91
    .build();
92

93
SqsClient sqs = SqsClient.builder()
94
    .endpointOverride(mainEndpoint)
95
    .credentialsProvider(StaticCredentialsProvider.create(
96
        AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
97
    ))
98
    .region(Region.of(localstack.getRegion()))
99
    .build();
100
```
101

102
### AWS Credentials
103

104
Get default AWS credentials configured for LocalStack access.
105

106
```java { .api }
107
/**
108
 * Provides default AWS access key for LocalStack authentication
109
 * @return AWS access key string (default: "test")
110
 */
111
public String getAccessKey();
112

113
/**
114
 * Provides default AWS secret key for LocalStack authentication  
115
 * @return AWS secret key string (default: "test")
116
 */
117
public String getSecretKey();
118
```
119

120
**Usage Examples:**
121

122
```java
123
// Get credentials
124
String accessKey = localstack.getAccessKey();     // "test" by default
125
String secretKey = localstack.getSecretKey();     // "test" by default
126

127
// Use with AWS SDK v1
128
BasicAWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey);
129
AWSStaticCredentialsProvider credentialsProvider = new AWSStaticCredentialsProvider(credentials);
130

131
// Use with AWS SDK v2
132
AwsBasicCredentials awsCredentials = AwsBasicCredentials.create(accessKey, secretKey);
133
StaticCredentialsProvider credentialsProvider = StaticCredentialsProvider.create(awsCredentials);
134
```
135

136
### AWS Region
137

138
Get the default AWS region configured for LocalStack.
139

140
```java { .api }
141
/**
142
 * Provides default AWS region for LocalStack services
143
 * @return AWS region string (default: "us-east-1")
144
 */
145
public String getRegion();
146
```
147

148
**Usage Examples:**
149

150
```java
151
// Get region
152
String region = localstack.getRegion();           // "us-east-1" by default
153

154
// Use with AWS SDK v1 clients
155
Region awsRegion = Region.getRegion(Regions.fromName(region));
156

157
// Use with AWS SDK v2 clients  
158
Region regionV2 = Region.of(region);
159
```
160

161
## Complete AWS SDK Integration Examples
162

163
### AWS SDK v1 Integration
164

165
```java
166
import com.amazonaws.auth.AWSStaticCredentialsProvider;
167
import com.amazonaws.auth.BasicAWSCredentials;
168
import com.amazonaws.client.builder.AwsClientBuilder;
169
import com.amazonaws.services.s3.AmazonS3;
170
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
171
import com.amazonaws.services.sqs.AmazonSQS;
172
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
173

174
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
175
    .withServices(Service.S3, Service.SQS);
176

177
// Configure S3 client
178
AmazonS3 s3 = AmazonS3ClientBuilder
179
    .standard()
180
    .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
181
        localstack.getEndpointOverride(Service.S3).toString(),
182
        localstack.getRegion()
183
    ))
184
    .withCredentials(new AWSStaticCredentialsProvider(
185
        new BasicAWSCredentials(localstack.getAccessKey(), localstack.getSecretKey())
186
    ))
187
    .build();
188

189
// Configure SQS client
190
AmazonSQS sqs = AmazonSQSClientBuilder
191
    .standard()
192
    .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
193
        localstack.getEndpointOverride(Service.SQS).toString(),
194
        localstack.getRegion()
195
    ))
196
    .withCredentials(new AWSStaticCredentialsProvider(
197
        new BasicAWSCredentials(localstack.getAccessKey(), localstack.getSecretKey())
198
    ))
199
    .build();
200
```
201

202
### AWS SDK v2 Integration
203

204
```java
205
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
206
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
207
import software.amazon.awssdk.regions.Region;
208
import software.amazon.awssdk.services.s3.S3Client;
209
import software.amazon.awssdk.services.sqs.SqsClient;
210
import software.amazon.awssdk.services.lambda.LambdaClient;
211

212
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
213
    .withServices(Service.S3, Service.SQS, Service.LAMBDA);
214

215
// Create reusable credentials provider
216
StaticCredentialsProvider credentialsProvider = StaticCredentialsProvider.create(
217
    AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
218
);
219
Region region = Region.of(localstack.getRegion());
220

221
// Configure S3 client
222
S3Client s3 = S3Client.builder()
223
    .endpointOverride(localstack.getEndpointOverride(Service.S3))
224
    .credentialsProvider(credentialsProvider)
225
    .region(region)
226
    .build();
227

228
// Configure SQS client
229
SqsClient sqs = SqsClient.builder()
230
    .endpointOverride(localstack.getEndpointOverride(Service.SQS))
231
    .credentialsProvider(credentialsProvider)
232
    .region(region)
233
    .build();
234

235
// Configure Lambda client
236
LambdaClient lambda = LambdaClient.builder()
237
    .endpointOverride(localstack.getEndpointOverride(Service.LAMBDA))
238
    .credentialsProvider(credentialsProvider)
239
    .region(region)
240
    .build();
241
```
242

243
### Custom Credentials and Region
244

245
Override default credentials and region using environment variables:
246

247
```java
248
LocalStackContainer localstack = new LocalStackContainer(localstackImage)
249
    .withServices(Service.S3)
250
    .withEnv("AWS_ACCESS_KEY_ID", "custom-access-key")
251
    .withEnv("AWS_SECRET_ACCESS_KEY", "custom-secret-key")
252
    .withEnv("DEFAULT_REGION", "eu-west-1");
253

254
// These will return the custom values
255
String customAccessKey = localstack.getAccessKey();    // "custom-access-key"
256
String customSecretKey = localstack.getSecretKey();    // "custom-secret-key"  
257
String customRegion = localstack.getRegion();          // "eu-west-1"
258
```
259

260
## Network-Aware Endpoint Resolution
261

262
The endpoint methods automatically handle different networking scenarios:
263

264
- **Bridge Network**: Returns host-accessible endpoint using container host and mapped ports
265
- **Custom Docker Network**: Uses network aliases for inter-container communication
266
- **IP Resolution**: Resolves hostnames to IP addresses for S3 path-style access compatibility
267

268
This ensures endpoints work correctly whether your tests run from the host or from other containers within the same Docker network.