0
# AWS Services
1
2
LocalStack provides comprehensive AWS service emulation through a pluggable provider system, supporting 45+ AWS services with high-fidelity APIs. The AWS Service Framework (ASF) enables extensible service implementations while maintaining compatibility with AWS SDKs and tools.
3
4
## Capabilities
5
6
### Service Management
7
8
Core classes and functions for managing LocalStack's AWS service lifecycle and state.
9
10
```python { .api }
11
class ServiceManager:
12
"""
13
Central manager for LocalStack service instances and lifecycle.
14
15
Location: localstack.services.plugins
16
"""
17
18
def get_service(self, name: str) -> Service | None:
19
"""
20
Retrieve service instance by name.
21
22
Args:
23
name: AWS service name (e.g., 's3', 'lambda', 'dynamodb')
24
25
Returns:
26
Service instance if found, None otherwise
27
"""
28
29
def add_service(self, service: 'Service') -> bool:
30
"""
31
Register a new service with the manager.
32
33
Args:
34
service: Service instance to register
35
36
Returns:
37
True if service was added successfully
38
"""
39
40
def require(self, name: str) -> 'Service':
41
"""
42
Get service instance, raising exception if not found.
43
44
Args:
45
name: AWS service name
46
47
Returns:
48
Service instance
49
50
Raises:
51
ServiceException: If service not found or not available
52
"""
53
54
def is_running(self, name: str) -> bool:
55
"""
56
Check if service is currently running.
57
58
Args:
59
name: AWS service name
60
61
Returns:
62
True if service is in RUNNING state
63
"""
64
65
def get_states(self) -> dict[str, 'ServiceState']:
66
"""
67
Get current state of all registered services.
68
69
Returns:
70
Dictionary mapping service names to their current states
71
"""
72
73
class Service:
74
"""
75
Individual AWS service instance with lifecycle management.
76
77
Location: localstack.services.plugins
78
"""
79
80
def __init__(
81
self,
82
name: str,
83
start: callable = None,
84
check: callable = None,
85
skeleton=None,
86
active: bool = False,
87
stop: callable = None
88
):
89
"""
90
Initialize service instance.
91
92
Args:
93
name: Service name (e.g., 's3', 'lambda')
94
start: Function to start the service
95
check: Function to check service health
96
skeleton: ASF skeleton for API handling
97
active: Whether service starts automatically
98
stop: Function to stop the service
99
"""
100
101
def start(self, asynchronous: bool = True) -> None:
102
"""
103
Start the service instance.
104
105
Args:
106
asynchronous: Whether to start asynchronously
107
"""
108
109
def stop(self) -> None:
110
"""Stop the service instance and clean up resources."""
111
112
def check(
113
self,
114
expect_shutdown: bool = False,
115
print_error: bool = False
116
) -> bool:
117
"""
118
Check service health and readiness.
119
120
Args:
121
expect_shutdown: Whether service shutdown is expected
122
print_error: Whether to print error details
123
124
Returns:
125
True if service is healthy
126
"""
127
128
def is_enabled(self) -> bool:
129
"""
130
Check if service is enabled in current configuration.
131
132
Returns:
133
True if service is enabled
134
"""
135
136
class ServiceState(Enum):
137
"""
138
Service lifecycle states.
139
140
Location: localstack.services.plugins
141
"""
142
UNKNOWN = "unknown" # State cannot be determined
143
AVAILABLE = "available" # Service available but not started
144
DISABLED = "disabled" # Service disabled in configuration
145
STARTING = "starting" # Service is starting up
146
RUNNING = "running" # Service is fully operational
147
STOPPING = "stopping" # Service is shutting down
148
STOPPED = "stopped" # Service has been stopped
149
ERROR = "error" # Service encountered an error
150
```
151
152
### Service Provider System
153
154
Plugin-based architecture for implementing AWS service emulation with the ASF framework.
155
156
```python { .api }
157
def aws_provider(
158
api: str = None,
159
name: str = "default",
160
should_load: callable = None
161
) -> callable:
162
"""
163
Decorator for registering AWS service providers.
164
165
Args:
166
api: AWS service API name (e.g., 's3', 'lambda')
167
name: Provider name (default: "default")
168
should_load: Optional function to determine if provider should load
169
170
Returns:
171
Decorator function for provider classes
172
173
Location: localstack.services.plugins
174
"""
175
176
class ServiceProvider(Protocol):
177
"""
178
Protocol for AWS service provider implementations.
179
180
Location: localstack.services.plugins
181
"""
182
service: str # AWS service name this provider implements
183
184
class ServicePlugin:
185
"""
186
Plugin wrapper for service providers.
187
188
Location: localstack.services.plugins
189
"""
190
service: str # Service name
191
api: str # AWS API name
192
193
def create_service(self) -> Service:
194
"""
195
Create service instance from this plugin.
196
197
Returns:
198
Configured Service instance
199
"""
200
201
# Plugin namespace for service providers
202
PLUGIN_NAMESPACE: str = "localstack.aws.provider"
203
```
204
205
### AWS Service Framework (ASF)
206
207
Core framework components for high-fidelity AWS API emulation.
208
209
```python { .api }
210
class Skeleton:
211
"""
212
ASF skeleton for AWS service API scaffolding.
213
214
Location: localstack.aws.skeleton
215
"""
216
217
def __init__(self, service: 'ServiceModel', delegate):
218
"""
219
Initialize skeleton with service model and implementation delegate.
220
221
Args:
222
service: AWS service model specification
223
delegate: Implementation object for service operations
224
"""
225
226
def load_service(service_name: str) -> 'ServiceModel':
227
"""
228
Load AWS service specification model.
229
230
Args:
231
service_name: AWS service name (e.g., 's3', 'dynamodb')
232
233
Returns:
234
ServiceModel with API specifications
235
236
Location: localstack.aws.spec
237
"""
238
```
239
240
### AWS Client Integration
241
242
LocalStack's AWS client connectivity and service integration functions.
243
244
```python { .api }
245
class InternalClientFactory:
246
"""
247
Factory for creating AWS clients connected to LocalStack endpoint.
248
249
Location: localstack.aws.connect
250
"""
251
252
def get_client(
253
self,
254
service_name: str,
255
region_name: str = None,
256
aws_access_key_id: str = None,
257
aws_secret_access_key: str = None,
258
aws_session_token: str = None,
259
endpoint_url: str = None,
260
config = None
261
) -> object:
262
"""
263
Create AWS service client with LocalStack configuration.
264
265
Args:
266
service_name: AWS service name (e.g., 's3', 'lambda')
267
region_name: AWS region (defaults to us-east-1)
268
endpoint_url: LocalStack endpoint URL
269
**kwargs: Additional boto3 client parameters
270
271
Returns:
272
Configured boto3 client instance
273
"""
274
275
# Factory instances
276
connect_to: InternalClientFactory # For internal LocalStack connections
277
connect_externally_to: "ExternalClientFactory" # For external connections
278
```
279
280
## Supported Services
281
282
LocalStack provides emulation for 45+ AWS services organized by category:
283
284
### Core Services
285
286
Essential AWS services for most cloud applications.
287
288
```python { .api }
289
# Core service identifiers
290
CORE_SERVICES: list[str] = [
291
"s3", # Simple Storage Service
292
"lambda", # Function compute
293
"dynamodb", # NoSQL database
294
"sqs", # Simple Queue Service
295
"sns", # Simple Notification Service
296
"iam", # Identity and Access Management
297
"sts", # Security Token Service
298
"cloudformation", # Infrastructure as Code
299
"cloudwatch", # Monitoring and logging
300
"apigateway", # REST/HTTP APIs
301
]
302
```
303
304
### Compute Services
305
306
Virtual machines, containers, and serverless compute.
307
308
- **EC2** - Elastic Compute Cloud (virtual machines)
309
- **ECS** - Elastic Container Service
310
- **ECR** - Elastic Container Registry
311
- **Lambda** - Serverless functions
312
- **Step Functions** - State machine orchestration
313
- **Batch** - Batch job processing
314
315
### Storage Services
316
317
Object storage, file systems, and data archival.
318
319
- **S3** - Simple Storage Service (object storage)
320
- **EFS** - Elastic File System
321
- **Glacier** - Long-term archival storage
322
323
### Database Services
324
325
Relational, NoSQL, and specialized databases.
326
327
- **DynamoDB** - NoSQL database
328
- **RDS** - Relational Database Service
329
- **ElastiCache** - In-memory caching
330
- **Redshift** - Data warehouse
331
- **OpenSearch/ES** - Search and analytics engine
332
333
### Messaging and Streaming
334
335
Queue, notification, and data streaming services.
336
337
- **SQS** - Simple Queue Service
338
- **SNS** - Simple Notification Service
339
- **Kinesis** - Real-time data streaming
340
- **Kinesis Firehose** - Data delivery streams
341
342
### Application Services
343
344
API management, email, and application integration.
345
346
- **API Gateway** - REST and HTTP API management
347
- **SES** - Simple Email Service
348
- **Secrets Manager** - Secret storage and rotation
349
- **SSM** - Systems Manager (Parameter Store)
350
- **AppSync** - GraphQL API service
351
352
### Security and Identity
353
354
Authentication, authorization, and key management.
355
356
- **IAM** - Identity and Access Management
357
- **STS** - Security Token Service
358
- **KMS** - Key Management Service
359
- **ACM** - Certificate Manager
360
361
### Networking and Content Delivery
362
363
DNS, load balancing, and content distribution.
364
365
- **Route53** - DNS and domain management
366
- **CloudFront** - Content Delivery Network
367
- **ELB** - Elastic Load Balancing
368
369
### Management and Monitoring
370
371
Resource management, monitoring, and operations.
372
373
- **CloudFormation** - Infrastructure as Code
374
- **CloudWatch** - Monitoring and metrics
375
- **CloudTrail** - API call logging
376
- **Organizations** - Multi-account management
377
378
## Usage Examples
379
380
### Basic Service Usage
381
382
```python
383
from localstack.aws.connect import connect_to
384
import boto3
385
386
# Using LocalStack's client factory
387
s3 = connect_to().s3
388
dynamodb = connect_to().dynamodb
389
390
# Using boto3 directly with LocalStack endpoint
391
sqs = boto3.client(
392
'sqs',
393
endpoint_url='http://localhost:4566',
394
aws_access_key_id='test',
395
aws_secret_access_key='test',
396
region_name='us-east-1'
397
)
398
399
# Create resources
400
s3.create_bucket(Bucket='my-bucket')
401
dynamodb.create_table(
402
TableName='my-table',
403
KeySchema=[{'AttributeName': 'id', 'KeyType': 'HASH'}],
404
AttributeDefinitions=[{'AttributeName': 'id', 'AttributeType': 'S'}],
405
BillingMode='PAY_PER_REQUEST'
406
)
407
queue_url = sqs.create_queue(QueueName='my-queue')['QueueUrl']
408
```
409
410
### Service Health Monitoring
411
412
```python
413
from localstack.services.plugins import ServiceManager
414
415
# Get service manager instance
416
manager = ServiceManager()
417
418
# Check individual service
419
if manager.is_running("s3"):
420
print("S3 service is running")
421
422
# Get all service states
423
states = manager.get_states()
424
for service_name, state in states.items():
425
print(f"{service_name}: {state.value}")
426
427
# Ensure required services are available
428
try:
429
s3_service = manager.require("s3")
430
lambda_service = manager.require("lambda")
431
print("Required services are available")
432
except Exception as e:
433
print(f"Service requirement not met: {e}")
434
```
435
436
### Custom Service Provider
437
438
```python
439
from localstack.services.plugins import aws_provider, ServiceProvider
440
441
@aws_provider(api="myservice")
442
class MyServiceProvider(ServiceProvider):
443
"""Custom AWS service provider implementation"""
444
445
service = "myservice"
446
447
def create_bucket(self, context, request):
448
"""Example service operation implementation"""
449
bucket_name = request["Bucket"]
450
# Custom implementation logic
451
return {"Location": f"/{bucket_name}"}
452
453
def list_buckets(self, context, request):
454
"""List all buckets"""
455
# Custom implementation logic
456
return {
457
"Buckets": [],
458
"Owner": {"ID": "localstack", "DisplayName": "LocalStack"}
459
}
460
```
461
462
### Service Configuration
463
464
```python
465
# Environment variables for service control
466
import os
467
468
# Enable specific services only
469
os.environ["SERVICES"] = "s3,lambda,dynamodb"
470
471
# Eager loading for faster startup
472
os.environ["EAGER_SERVICE_LOADING"] = "1"
473
474
# Strict service loading validation
475
os.environ["STRICT_SERVICE_LOADING"] = "1"
476
477
# Service-specific configuration
478
os.environ["S3_SKIP_SIGNATURE_VALIDATION"] = "1"
479
os.environ["LAMBDA_EXECUTOR"] = "docker"
480
os.environ["DYNAMODB_ERROR_PROBABILITY"] = "0.0"
481
```
482
483
## HTTP/Runtime APIs
484
485
### Health Check Endpoint
486
487
LocalStack provides HTTP endpoints for service health monitoring and control.
488
489
```python { .api }
490
# Health check endpoint
491
GET /_localstack/health
492
493
# Response format:
494
{
495
"services": {
496
"s3": "running",
497
"lambda": "running",
498
"dynamodb": "available",
499
"sqs": "starting"
500
}
501
}
502
503
# Control operations
504
POST /_localstack/health
505
{
506
"action": "restart" # Control action
507
}
508
```
509
510
### Internal Headers
511
512
HTTP headers used by LocalStack for request routing and service targeting.
513
514
```python { .api }
515
# LocalStack-specific headers (from localstack.constants)
516
HEADER_LOCALSTACK_EDGE_URL: str = "x-localstack-edge" # Proxy forwarding
517
HEADER_LOCALSTACK_REQUEST_URL: str = "x-localstack-request-url" # Original URL
518
HEADER_LOCALSTACK_TARGET: str = "x-localstack-target" # Target service
519
HEADER_LOCALSTACK_IDENTIFIER: str = "x-localstack" # LocalStack identifier
520
HEADER_LOCALSTACK_AUTHORIZATION: str = "x-localstack-authorization" # Custom auth
521
522
# AWS-compatible headers
523
HEADER_AMZN_ERROR_TYPE: str = "X-Amzn-Errortype" # AWS error type
524
```
525
526
Usage in requests:
527
528
```python
529
import requests
530
531
# Direct service targeting
532
response = requests.get(
533
'http://localhost:4566/',
534
headers={
535
'x-localstack-target': 's3',
536
'Authorization': 'AWS4-HMAC-SHA256 ...'
537
}
538
)
539
540
# Health check
541
health = requests.get('http://localhost:4566/_localstack/health')
542
print(health.json())
543
```