0
# Alias and Version Management
1

2
Comprehensive version control and alias management for Lambda functions, enabling immutable versioning, traffic splitting, and deployment strategies through function aliases and version publishing.
3

4
## Capabilities
5

6
### Version Publishing
7

8
Creates an immutable version from the current function code and configuration.
9

10
```java { .api }
11
/**
12
 * Creates an immutable version from current function code and configuration
13
 * @param request Version publishing parameters including function name and description
14
 * @return PublishVersionResult containing version configuration details
15
 * @throws ServiceException if service encounters an error
16
 * @throws ResourceNotFoundException if function does not exist
17
 * @throws InvalidParameterValueException if parameters are invalid
18
 */
19
PublishVersionResult publishVersion(PublishVersionRequest request);
20

21
public class PublishVersionRequest {
22
    /** Function name (required) - name, ARN, or partial ARN */
23
    private String functionName;
24
    /** SHA256 hash of ZIP file (optional) - ensures version consistency */
25
    private String codeSha256;
26
    /** Version description (optional) - up to 256 characters */
27
    private String description;
28
    /** Whether to publish function (optional, default: false) */
29
    private Boolean revisionId;
30
}
31

32
public class PublishVersionResult {
33
    /** Function name */
34
    private String functionName;
35
    /** Function ARN */
36
    private String functionArn;
37
    /** Runtime environment */
38
    private Runtime runtime;
39
    /** IAM role ARN */
40
    private String role;
41
    /** Function handler */
42
    private String handler;
43
    /** SHA256 of function code */
44
    private String codeSha256;
45
    /** Function code size in bytes */
46
    private Long codeSize;
47
    /** Function description */
48
    private String description;
49
    /** Timeout in seconds */
50
    private Integer timeout;
51
    /** Memory size in MB */
52
    private Integer memorySize;
53
    /** Last modified timestamp */
54
    private String lastModified;
55
    /** Version number */
56
    private String version;
57
    /** VPC configuration */
58
    private VpcConfigResponse vpcConfig;
59
    /** Dead letter queue configuration */
60
    private DeadLetterConfig deadLetterConfig;
61
    /** Environment variables */
62
    private EnvironmentResponse environment;
63
    /** KMS key ARN */
64
    private String kmsKeyArn;
65
    /** X-Ray tracing configuration */
66
    private TracingConfigResponse tracingConfig;
67
    /** Function state */
68
    private State state;
69
    /** State reason */
70
    private String stateReason;
71
    /** State reason code */
72
    private StateReasonCode stateReasonCode;
73
    /** Last update status */
74
    private LastUpdateStatus lastUpdateStatus;
75
    /** Last update status reason */
76
    private String lastUpdateStatusReason;
77
    /** Architecture */
78
    private Architecture architecture;
79
}
80
```
81

82
### List Function Versions
83

84
Lists all versions for a specific function.
85

86
```java { .api }
87
/**
88
 * Lists all versions for a specific function
89
 * @param request Version listing parameters including function name and pagination
90
 * @return ListVersionsByFunctionResult containing version list and pagination info
91
 * @throws ServiceException if service encounters an error
92
 * @throws ResourceNotFoundException if function does not exist
93
 */
94
ListVersionsByFunctionResult listVersionsByFunction(ListVersionsByFunctionRequest request);
95

96
public class ListVersionsByFunctionRequest {
97
    /** Function name (required) - name, ARN, or partial ARN */
98
    private String functionName;
99
    /** Pagination marker (optional) */
100
    private String marker;
101
    /** Maximum items to return (optional, range: 1-50) */
102
    private Integer maxItems;
103
}
104

105
public class ListVersionsByFunctionResult {
106
    /** Pagination marker for next page */
107
    private String nextMarker;
108
    /** List of function versions */
109
    private List<FunctionConfiguration> versions;
110
}
111
```
112

113
### Alias Creation
114

115
Creates a function alias with optional traffic splitting support.
116

117
```java { .api }
118
/**
119
 * Creates a function alias with traffic splitting capabilities
120
 * @param request Alias creation parameters including name, version, and traffic weights
121
 * @return CreateAliasResult containing alias configuration details
122
 * @throws ServiceException if service encounters an error
123
 * @throws ResourceConflictException if alias already exists
124
 * @throws InvalidParameterValueException if parameters are invalid
125
 */
126
CreateAliasResult createAlias(CreateAliasRequest request);
127

128
public class CreateAliasRequest {
129
    /** Function name (required) - name, ARN, or partial ARN */
130
    private String functionName;
131
    /** Alias name (required) - 1-128 characters, pattern: (?!^[0-9]+$)([a-zA-Z0-9-_]+) */
132
    private String name;
133
    /** Function version (required) - version number or $LATEST */
134
    private String functionVersion;
135
    /** Alias description (optional) - up to 256 characters */
136
    private String description;
137
    /** Additional version weights for traffic splitting (optional) */
138
    private Map<String, Double> additionalVersionWeights;
139
    /** Routing configuration (optional) */
140
    private AliasRoutingConfiguration routingConfig;
141
}
142

143
public class CreateAliasResult {
144
    /** Alias ARN */
145
    private String aliasArn;
146
    /** Alias name */
147
    private String name;
148
    /** Function version */
149
    private String functionVersion;
150
    /** Alias description */
151
    private String description;
152
    /** Additional version weights */
153
    private Map<String, Double> additionalVersionWeights;
154
    /** Routing configuration */
155
    private AliasRoutingConfiguration routingConfig;
156
    /** Revision ID */
157
    private String revisionId;
158
}
159

160
public class AliasRoutingConfiguration {
161
    /** Additional version weights for traffic routing */
162
    private Map<String, Double> additionalVersionWeights;
163
}
164
```
165

166
### Alias Updates
167

168
Updates existing alias configuration including version and traffic weights.
169

170
```java { .api }
171
/**
172
 * Updates existing alias configuration
173
 * @param request Alias update parameters including name, version, and traffic weights
174
 * @return UpdateAliasResult containing updated alias configuration
175
 * @throws ServiceException if service encounters an error
176
 * @throws ResourceNotFoundException if alias does not exist
177
 * @throws InvalidParameterValueException if parameters are invalid
178
 */
179
UpdateAliasResult updateAlias(UpdateAliasRequest request);
180

181
public class UpdateAliasRequest {
182
    /** Function name (required) - name, ARN, or partial ARN */
183
    private String functionName;
184
    /** Alias name (required) */
185
    private String name;
186
    /** Function version (optional) - version number or $LATEST */
187
    private String functionVersion;
188
    /** Alias description (optional) */
189
    private String description;
190
    /** Additional version weights (optional) */
191
    private Map<String, Double> additionalVersionWeights;
192
    /** Routing configuration (optional) */
193
    private AliasRoutingConfiguration routingConfig;
194
    /** Revision ID for optimistic locking (optional) */
195
    private String revisionId;
196
}
197

198
public class UpdateAliasResult {
199
    /** Alias ARN */
200
    private String aliasArn;
201
    /** Alias name */
202
    private String name;
203
    /** Function version */
204
    private String functionVersion;
205
    /** Alias description */
206
    private String description;
207
    /** Additional version weights */
208
    private Map<String, Double> additionalVersionWeights;
209
    /** Routing configuration */
210
    private AliasRoutingConfiguration routingConfig;
211
    /** Revision ID */
212
    private String revisionId;
213
}
214
```
215

216
### Alias Retrieval
217

218
Retrieves configuration details for a specific alias.
219

220
```java { .api }
221
/**
222
 * Retrieves alias configuration details
223
 * @param request Alias retrieval parameters including function and alias names
224
 * @return GetAliasResult containing alias configuration
225
 * @throws ServiceException if service encounters an error
226
 * @throws ResourceNotFoundException if alias does not exist
227
 */
228
GetAliasResult getAlias(GetAliasRequest request);
229

230
public class GetAliasRequest {
231
    /** Function name (required) - name, ARN, or partial ARN */
232
    private String functionName;
233
    /** Alias name (required) */
234
    private String name;
235
}
236

237
public class GetAliasResult {
238
    /** Alias ARN */
239
    private String aliasArn;
240
    /** Alias name */
241
    private String name;
242
    /** Function version */
243
    private String functionVersion;
244
    /** Alias description */
245
    private String description;
246
    /** Additional version weights */
247
    private Map<String, Double> additionalVersionWeights;
248
    /** Routing configuration */
249
    private AliasRoutingConfiguration routingConfig;
250
    /** Revision ID */
251
    private String revisionId;
252
}
253
```
254

255
### Alias Deletion
256

257
Deletes a function alias.
258

259
```java { .api }
260
/**
261
 * Deletes a function alias
262
 * @param request Alias deletion parameters including function and alias names
263
 * @return DeleteAliasResult indicating successful deletion
264
 * @throws ServiceException if service encounters an error
265
 * @throws ResourceNotFoundException if alias does not exist
266
 */
267
DeleteAliasResult deleteAlias(DeleteAliasRequest request);
268

269
public class DeleteAliasRequest {
270
    /** Function name (required) - name, ARN, or partial ARN */
271
    private String functionName;
272
    /** Alias name (required) */
273
    private String name;
274
}
275

276
public class DeleteAliasResult {
277
    // Empty result indicating successful deletion
278
}
279
```
280

281
### Alias Listing
282

283
Lists all aliases for a specific function.
284

285
```java { .api }
286
/**
287
 * Lists all aliases for a specific function
288
 * @param request Alias listing parameters including function name and pagination
289
 * @return ListAliasesResult containing alias list and pagination info
290
 * @throws ServiceException if service encounters an error
291
 * @throws ResourceNotFoundException if function does not exist
292
 */
293
ListAliasesResult listAliases(ListAliasesRequest request);
294

295
public class ListAliasesRequest {
296
    /** Function name (required) - name, ARN, or partial ARN */
297
    private String functionName;
298
    /** Function version (optional) - filter aliases by version */
299
    private String functionVersion;
300
    /** Pagination marker (optional) */
301
    private String marker;
302
    /** Maximum items to return (optional, range: 1-50) */
303
    private Integer maxItems;
304
}
305

306
public class ListAliasesResult {
307
    /** Pagination marker for next page */
308
    private String nextMarker;
309
    /** List of function aliases */
310
    private List<AliasConfiguration> aliases;
311
}
312

313
public class AliasConfiguration {
314
    /** Alias ARN */
315
    private String aliasArn;
316
    /** Alias name */
317
    private String name;
318
    /** Function version */
319
    private String functionVersion;
320
    /** Alias description */
321
    private String description;
322
    /** Additional version weights */
323
    private Map<String, Double> additionalVersionWeights;
324
    /** Routing configuration */
325
    private AliasRoutingConfiguration routingConfig;
326
    /** Revision ID */
327
    private String revisionId;
328
}
329
```
330

331
## Usage Examples
332

333
### Publishing a Version
334

335
```java
336
AWSLambda lambdaClient = AWSLambdaClientBuilder.defaultClient();
337

338
PublishVersionRequest request = new PublishVersionRequest()
339
    .withFunctionName("my-function")
340
    .withDescription("Production release v1.2.0")
341
    .withCodeSha256("abc123def456..."); // Optional: ensure specific code version
342

343
PublishVersionResult result = lambdaClient.publishVersion(request);
344
System.out.println("Published version: " + result.getVersion());
345
```
346

347
### Creating an Alias with Traffic Splitting
348

349
```java
350
// Create alias with 90% traffic to version 2, 10% to version 1
351
Map<String, Double> weights = new HashMap<>();
352
weights.put("1", 0.1);
353

354
CreateAliasRequest request = new CreateAliasRequest()
355
    .withFunctionName("my-function")
356
    .withName("live")
357
    .withFunctionVersion("2")
358
    .withDescription("Production alias")
359
    .withAdditionalVersionWeights(weights);
360

361
CreateAliasResult result = lambdaClient.createAlias(request);
362
System.out.println("Created alias ARN: " + result.getAliasArn());
363
```
364

365
### Gradually Shifting Traffic
366

367
```java
368
// Shift traffic from version 1 to version 2 (50/50 split)
369
Map<String, Double> newWeights = new HashMap<>();
370
newWeights.put("1", 0.5);
371

372
UpdateAliasRequest request = new UpdateAliasRequest()
373
    .withFunctionName("my-function")
374
    .withName("live")
375
    .withFunctionVersion("2")
376
    .withAdditionalVersionWeights(newWeights);
377

378
UpdateAliasResult result = lambdaClient.updateAlias(request);
379
```
380

381
### Listing Function Versions
382

383
```java
384
ListVersionsByFunctionRequest request = new ListVersionsByFunctionRequest()
385
    .withFunctionName("my-function")
386
    .withMaxItems(10);
387

388
ListVersionsByFunctionResult result = lambdaClient.listVersionsByFunction(request);
389
for (FunctionConfiguration version : result.getVersions()) {
390
    System.out.println("Version " + version.getVersion() + 
391
                      ": " + version.getDescription());
392
}
393
```
394

395
## Exception Handling
396

397
Common exceptions when working with aliases and versions:
398

399
- **ResourceNotFoundException**: Function or alias does not exist
400
- **ResourceConflictException**: Alias name already exists during creation
401
- **InvalidParameterValueException**: Invalid function name, alias name, or version
402
- **ServiceException**: General service errors
403
- **TooManyRequestsException**: Rate limiting exceeded
404
- **ResourceNotReadyException**: Function is not ready for version publishing
405

406
## Best Practices
407

408
### Version Management
409
- Use meaningful descriptions when publishing versions
410
- Include code SHA256 hash to ensure version consistency
411
- Implement automated version publishing in CI/CD pipelines
412
- Keep version history manageable by periodically reviewing old versions
413

414
### Alias Strategy
415
- Use aliases for environment separation (dev, staging, prod)
416
- Implement blue-green deployments using traffic splitting
417
- Use descriptive alias names that indicate their purpose
418
- Monitor traffic distribution when using weighted routing
419

420
### Traffic Splitting
421
- Start with small traffic percentages for canary deployments
422
- Monitor metrics and error rates during traffic shifts
423
- Use CloudWatch alarms to automatically rollback on errors
424
- Gradually increase traffic to new versions based on success metrics