Skip to content

Commit 320d85b

Browse files
ncipollinaclaude
ncipollina
and
claude
authored
docs: Complete v2.0.0 release documentation and version finalization (#27)
* release: remove -beta suffix from version 2.0.0 - Update VersionPrefix from 2.0.0-beta to 2.0.0 - Ready for stable release after testing confirmation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add comprehensive CHANGELOG.md for v2.0.0 release - Document breaking changes in OTEL layer configuration - Provide detailed migration guide from v1.x to v2.0+ - Include examples of new Architecture and OtelLayerVersion properties - Document all new features and changed defaults - Add proper semantic versioning information 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: update all documentation for OTEL layer v2.0.0 changes Updates include: **docs/index.md:** - Update feature descriptions to mention 'configurable' OTEL support - Add explicit IncludeOtelLayer = true to Quick Start example - Show breaking change in default behavior **docs/testing/index.md:** - Add new testing methods: WithOtelLayerVersion(), WithArchitecture() - Update inline data comments to reflect new OTEL defaults - Add comprehensive OTEL configuration section with examples - Document all new testing helper methods **docs/examples/index.md:** - Add explicit OTEL enablement to relevant examples - Create comprehensive 'OpenTelemetry Configuration Examples' section - Include migration examples from v1.x to v2.0+ - Show ARM64 architecture usage patterns - Add environment-specific OTEL configuration patterns - Update existing examples to demonstrate new properties All examples now clearly show that OTEL layer is opt-in in v2.0+ 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3ed0aae commit 320d85b

5 files changed

Lines changed: 244 additions & 8 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [2.0.0] - 2025-08-06
9+
10+
### ⚠️ BREAKING CHANGES
11+
12+
**OpenTelemetry Layer Configuration:**
13+
- **OpenTelemetry layer is now disabled by default** (was enabled by default in v1.x)
14+
- Added new required interface properties: `Architecture` and `OtelLayerVersion`
15+
16+
### ✨ Added
17+
18+
- **Configurable OTEL layer architecture**: Support for both `amd64` and `arm64` architectures via `Architecture` property (default: "amd64")
19+
- **Configurable OTEL layer version**: Control OTEL layer version via `OtelLayerVersion` property (default: "0-117-0")
20+
- **Dynamic OTEL layer ARN format**: Now uses configurable architecture and version: `arn:aws:lambda:{region}:901920570463:layer:aws-otel-collector-{architecture}-ver-{version}:1`
21+
- **Testing helpers**: New builder methods `WithOtelLayerVersion()` and `WithArchitecture()` for test configuration
22+
23+
### 🔄 Changed
24+
25+
- **`IncludeOtelLayer` default**: Changed from `true` to `false` **(BREAKING CHANGE)**
26+
- **Updated OTEL layer version**: Now defaults to latest version (0-117-0, was 0-102-1)
27+
- **Updated AWS CDK dependency**: Upgraded to v2.209.1 from v2.206.0
28+
- **Test defaults**: All test attributes and customizations now default to OTEL disabled
29+
30+
### 🐛 Fixed
31+
32+
- **Future-proof OTEL versioning**: No longer requires package updates when AWS releases new OTEL layer versions
33+
34+
### 📖 Migration Guide
35+
36+
#### For users upgrading from v1.x who want to maintain OTEL functionality:
37+
38+
**Before (v1.x - OTEL enabled by default):**
39+
```csharp
40+
var lambda = new LambdaFunctionConstruct(this, "MyLambda", new LambdaFunctionConstructProps
41+
{
42+
FunctionName = "my-api",
43+
FunctionSuffix = "prod",
44+
AssetPath = "./lambda.zip",
45+
RoleName = "my-api-role",
46+
PolicyName = "my-api-policy"
47+
// OTEL was enabled by default
48+
});
49+
```
50+
51+
**After (v2.0+ - OTEL must be explicitly enabled):**
52+
```csharp
53+
var lambda = new LambdaFunctionConstruct(this, "MyLambda", new LambdaFunctionConstructProps
54+
{
55+
FunctionName = "my-api",
56+
FunctionSuffix = "prod",
57+
AssetPath = "./lambda.zip",
58+
RoleName = "my-api-role",
59+
PolicyName = "my-api-policy",
60+
IncludeOtelLayer = true, // Must be explicitly enabled
61+
Architecture = "amd64", // Optional: specify architecture (default: amd64)
62+
OtelLayerVersion = "0-117-0" // Optional: specify version (default: latest)
63+
});
64+
```
65+
66+
#### Benefits of the new approach:
67+
68+
1. **Cost Control**: OTEL layer is now opt-in, preventing unexpected observability costs
69+
2. **Architecture Flexibility**: Support for both x86_64 (amd64) and ARM64 architectures
70+
3. **Version Control**: Specify exact OTEL layer versions for consistent deployments
71+
4. **Future Proof**: No more package updates needed when AWS releases new OTEL versions
72+
73+
#### Testing Updates:
74+
75+
**Before:**
76+
```csharp
77+
[LambdaFunctionConstructAutoData] // OTEL enabled by default
78+
public void Test_Lambda_With_OTEL(LambdaFunctionConstructProps props)
79+
```
80+
81+
**After:**
82+
```csharp
83+
[LambdaFunctionConstructAutoData(includeOtelLayer: true)] // Must explicitly enable
84+
public void Test_Lambda_With_OTEL(LambdaFunctionConstructProps props)
85+
```
86+
87+
## [1.0.1] - Previous Release
88+
89+
### 🔄 Changed
90+
- Package dependency updates
91+
- Documentation improvements
92+
93+
---
94+
95+
## Support
96+
97+
- **Issues**: [GitHub Issues](https://github.com/LayeredCraft/cdk-constructs/issues)
98+
- **Discussions**: [GitHub Discussions](https://github.com/LayeredCraft/cdk-constructs/discussions)
99+
- **Documentation**: [https://layeredcraft.github.io/cdk-constructs/](https://layeredcraft.github.io/cdk-constructs/)

‎Directory.Build.props‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<Project>
22
<PropertyGroup>
3-
<VersionPrefix>2.0.0-beta</VersionPrefix>
3+
<VersionPrefix>2.0.0</VersionPrefix>
44
<!-- SPDX license identifier for MIT -->
55
<PackageLicenseExpression>MIT</PackageLicenseExpression>
66

‎docs/examples/index.md‎

Lines changed: 118 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ public class ServerlessApiStack : Stack
4949
PolicyName = "user-api-policy",
5050
MemorySize = 1024,
5151
TimeoutInSeconds = 30,
52+
IncludeOtelLayer = true, // Enable OpenTelemetry for observability
5253
PolicyStatements = [
5354
new PolicyStatement(new PolicyStatementProps
5455
{
@@ -277,6 +278,121 @@ var table = new DynamoDbTableConstruct(this, "ComplexTable", new DynamoDbTableCo
277278
});
278279
```
279280

281+
## OpenTelemetry Configuration Examples
282+
283+
### Basic OTEL Enablement
284+
285+
```csharp
286+
var lambda = new LambdaFunctionConstruct(this, "BasicOtelLambda", new LambdaFunctionConstructProps
287+
{
288+
FunctionName = "my-api",
289+
FunctionSuffix = "prod",
290+
AssetPath = "./lambda.zip",
291+
RoleName = "my-api-role",
292+
PolicyName = "my-api-policy",
293+
IncludeOtelLayer = true // Enable OpenTelemetry (disabled by default in v2.0+)
294+
});
295+
```
296+
297+
### ARM64 Architecture with OTEL
298+
299+
```csharp
300+
var lambda = new LambdaFunctionConstruct(this, "Arm64OtelLambda", new LambdaFunctionConstructProps
301+
{
302+
FunctionName = "arm64-api",
303+
FunctionSuffix = "prod",
304+
AssetPath = "./lambda.zip",
305+
RoleName = "arm64-api-role",
306+
PolicyName = "arm64-api-policy",
307+
IncludeOtelLayer = true,
308+
Architecture = "arm64", // Use ARM64 for better cost/performance
309+
OtelLayerVersion = "0-117-0" // Specify exact OTEL version
310+
});
311+
```
312+
313+
### Different OTEL Layer Versions
314+
315+
```csharp
316+
// Production with latest stable OTEL
317+
var prodLambda = new LambdaFunctionConstruct(this, "ProdLambda", new LambdaFunctionConstructProps
318+
{
319+
FunctionName = "prod-api",
320+
FunctionSuffix = "prod",
321+
AssetPath = "./lambda.zip",
322+
RoleName = "prod-api-role",
323+
PolicyName = "prod-api-policy",
324+
IncludeOtelLayer = true,
325+
OtelLayerVersion = "0-117-0" // Latest stable version
326+
});
327+
328+
// Development with specific OTEL version for consistency
329+
var devLambda = new LambdaFunctionConstruct(this, "DevLambda", new LambdaFunctionConstructProps
330+
{
331+
FunctionName = "dev-api",
332+
FunctionSuffix = "dev",
333+
AssetPath = "./lambda.zip",
334+
RoleName = "dev-api-role",
335+
PolicyName = "dev-api-policy",
336+
IncludeOtelLayer = true,
337+
OtelLayerVersion = "0-115-0" // Previous version for testing
338+
});
339+
```
340+
341+
### Migration from v1.x Example
342+
343+
```csharp
344+
// v1.x approach (OTEL enabled by default)
345+
// var lambda = new LambdaFunctionConstruct(this, "Lambda", props);
346+
347+
// v2.0+ approach (OTEL must be explicitly enabled)
348+
var lambda = new LambdaFunctionConstruct(this, "Lambda", new LambdaFunctionConstructProps
349+
{
350+
FunctionName = "migrated-api",
351+
FunctionSuffix = "prod",
352+
AssetPath = "./lambda.zip",
353+
RoleName = "migrated-api-role",
354+
PolicyName = "migrated-api-policy",
355+
IncludeOtelLayer = true, // Must be explicit in v2.0+
356+
Architecture = "amd64", // Default, but now configurable
357+
OtelLayerVersion = "0-117-0" // Latest version
358+
});
359+
```
360+
361+
### Environment-Specific OTEL Configuration
362+
363+
```csharp
364+
public class OtelConfig
365+
{
366+
public bool EnableOtel { get; set; }
367+
public string Architecture { get; set; } = "amd64";
368+
public string OtelVersion { get; set; } = "0-117-0";
369+
}
370+
371+
public void CreateLambda(string environment, OtelConfig otelConfig)
372+
{
373+
var lambda = new LambdaFunctionConstruct(this, $"{environment}Lambda", new LambdaFunctionConstructProps
374+
{
375+
FunctionName = "my-api",
376+
FunctionSuffix = environment,
377+
AssetPath = "./lambda.zip",
378+
RoleName = $"my-api-{environment}-role",
379+
PolicyName = $"my-api-{environment}-policy",
380+
IncludeOtelLayer = otelConfig.EnableOtel,
381+
Architecture = otelConfig.Architecture,
382+
OtelLayerVersion = otelConfig.OtelVersion,
383+
EnvironmentVariables = new Dictionary<string, string>
384+
{
385+
{ "ENVIRONMENT", environment },
386+
{ "OTEL_ENABLED", otelConfig.EnableOtel.ToString() }
387+
}
388+
});
389+
}
390+
391+
// Usage:
392+
// CreateLambda("prod", new OtelConfig { EnableOtel = true, Architecture = "arm64" });
393+
// CreateLambda("dev", new OtelConfig { EnableOtel = false }); // No observability costs in dev
394+
```
395+
280396
## Testing Examples
281397

282398
### Complete Test Suite
@@ -373,7 +489,8 @@ public class MyStack : Stack
373489
PolicyName = $"my-function-{config.Environment}-policy",
374490
MemorySize = config.LambdaMemory,
375491
TimeoutInSeconds = config.LambdaTimeout,
376-
IncludeOtelLayer = config.EnableTracing
492+
IncludeOtelLayer = config.EnableTracing,
493+
Architecture = "amd64" // Configurable architecture
377494
});
378495

379496
if (!string.IsNullOrEmpty(config.DomainName))

‎docs/index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ A comprehensive library of reusable AWS CDK constructs for .NET projects, design
1111

1212
## Key Features
1313

14-
- **🚀 Lambda Functions**: Comprehensive Lambda construct with OpenTelemetry support, IAM management, and environment configuration
14+
- **🚀 Lambda Functions**: Comprehensive Lambda construct with configurable OpenTelemetry support, IAM management, and environment configuration
1515
- **🌐 Static Sites**: Complete static website hosting with S3, CloudFront, SSL certificates, and Route53 DNS management
1616
- **📊 DynamoDB Tables**: Full-featured DynamoDB construct with streams, TTL, and global secondary indexes
1717
- **🧪 Testing Helpers**: Extensive testing utilities with fluent assertions and builders
@@ -43,6 +43,7 @@ public class MyStack : Stack
4343
AssetPath = "./lambda-deployment.zip",
4444
RoleName = "my-api-role",
4545
PolicyName = "my-api-policy",
46+
IncludeOtelLayer = true, // Enable OpenTelemetry (disabled by default in v2.0+)
4647
GenerateUrl = true // Creates a Function URL for HTTP access
4748
});
4849

@@ -63,7 +64,7 @@ public class MyStack : Stack
6364

6465
Full-featured Lambda functions with:
6566

66-
- OpenTelemetry integration
67+
- Configurable OpenTelemetry integration
6768
- IAM roles and policies
6869
- Environment variables
6970
- Function URLs

‎docs/testing/index.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,30 @@ var props = CdkTestHelper.CreatePropsBuilder(AssetPathExtensions.GetTestLambdaZi
109109
.WithS3Access("my-bucket")
110110
.WithApiGatewayPermission("arn:aws:execute-api:us-east-1:123456789012:abcdef123/*")
111111
.WithOtelEnabled(true)
112+
.WithOtelLayerVersion("0-117-0")
113+
.WithArchitecture("arm64")
112114
.WithSnapStart(true)
113115
.WithGenerateUrl(true)
114116
.Build();
115117
```
116118

119+
### OpenTelemetry Configuration (v2.0+)
120+
121+
The props builder includes new methods for configuring OpenTelemetry settings:
122+
123+
```csharp
124+
var props = CdkTestHelper.CreatePropsBuilder(AssetPathExtensions.GetTestLambdaZipPath())
125+
.WithOtelEnabled(true) // Enable OTEL layer (disabled by default in v2.0+)
126+
.WithOtelLayerVersion("0-117-0") // Specify OTEL layer version
127+
.WithArchitecture("arm64") // Specify architecture (default: amd64)
128+
.Build();
129+
```
130+
131+
**Available OTEL methods:**
132+
- `WithOtelEnabled(bool)` - Enable/disable OpenTelemetry layer
133+
- `WithOtelLayerVersion(string)` - Specify OTEL layer version (e.g., "0-117-0")
134+
- `WithArchitecture(string)` - Specify Lambda architecture ("amd64" or "arm64")
135+
117136
### Assertion Methods
118137

119138
```csharp
@@ -239,10 +258,10 @@ public void Should_Create_Lambda_With_Custom_Settings(LambdaFunctionConstructPro
239258

240259
```csharp
241260
[Theory]
242-
[InlineData(true, true)] // OTEL enabled, permissions included
243-
[InlineData(true, false)] // OTEL enabled, no permissions
244-
[InlineData(false, true)] // OTEL disabled, permissions included
245-
[InlineData(false, false)] // OTEL disabled, no permissions
261+
[InlineData(true, true)] // OTEL explicitly enabled, permissions included
262+
[InlineData(true, false)] // OTEL explicitly enabled, no permissions
263+
[InlineData(false, true)] // OTEL disabled (default in v2.0+), permissions included
264+
[InlineData(false, false)] // OTEL disabled (default in v2.0+), no permissions
246265
public void Should_Handle_Different_Configurations(bool includeOtel, bool includePermissions)
247266
{
248267
var props = CdkTestHelper.CreatePropsBuilder(AssetPathExtensions.GetTestLambdaZipPath())

0 commit comments

Comments
 (0)