AWS cdk medium security documentation change
Summary
Updated versioning documentation with semantic versioning clarifications, including security-impacting changes and compatibility details
Security assessment
Added explicit section about 'Security impacting changes' stating backward incompatible API changes may be made to meet security requirements. This directly documents security-driven breaking changes as an exception to normal versioning rules.
Diff
diff --git a/cdk/v2/guide/versioning.md b/cdk/v2/guide/versioning.md index e70da99e7..d789167c5 100644 --- a//cdk/v2/guide/versioning.md +++ b//cdk/v2/guide/versioning.md @@ -5 +5 @@ -AWS CDK CLI compatibilityAWS Construct Library versioningLanguage binding stability +AWS CDK Toolkit compatibilityAWS Construct Library versioningAWS Construct Library semantic versioning clarificationsLanguage binding stability @@ -13 +13 @@ This topic provides reference information on how the AWS Cloud Development Kit ( -Version numbers consist of three numeric version parts: _major_._minor_._patch_ , and strictly adhere to the [semantic versioning](https://semver.org) model. This means that breaking changes to stable APIs are limited to major releases. +Version numbers consist of three numeric version parts: _major_._minor_._patch_ , and broadly follow [semantic versioning](https://semver.org) principles with a few caveats described in [AWS Construct Library semantic versioning clarifications](https://docs.aws.amazon.com/cdk/v2/guide/versioning.html#aws-construct-lib-semver). This means that breaking changes to APIs we consider stable are limited to major releases. @@ -15 +15 @@ Version numbers consist of three numeric version parts: _major_._minor_._patch_ -Minor and patch releases are backward compatible. The code written in a previous version with the same major version can be upgraded to a newer version within the same major version. It will also continue to build and run, producing the same output. +Minor and patch releases are backward compatible. The code written in a previous version with the same major version can be upgraded to a newer version within the same major version. It will continue to build and run, producing a functionally equivalent result. For some advanced use cases, small changes to your code will be required as noted in the next topic. @@ -17 +17 @@ Minor and patch releases are backward compatible. The code written in a previous -## AWS CDK CLI compatibility +## AWS CDK Toolkit compatibility @@ -19 +19 @@ Minor and patch releases are backward compatible. The code written in a previous -Each version of the main AWS CDK library (`aws-cdk-lib`) is compatible with the AWS CDK CLI (`aws-cdk-cli`) version that was current at the time of the CDK library’s release. It is also compatible with any newer version of the CDK CLI. Each version of the CDK library maintains this compatibility until the library’s _End of Life_ date. Therefore, as long as you’re using a supported CDK library version, it is always safe to upgrade your CDK CLI version. +Each version of the main AWS Construct Library (`aws-cdk-lib`) is compatible with the AWS CDK Toolkit CLI (`aws-cdk-cli`) and Toolkit Library (`@aws-cdk/toolkit-lib`) version that was current at the time of the AWS Construct Library’s release. It is also compatible with any newer version of the AWS CDK Toolkit. Each version of the AWS Construct Library maintains this compatibility until the library’s _End of Life_ date. Therefore, as long as you’re using a supported AWS Construct Library version, it is always safe to upgrade your AWS CDK Toolkit version. @@ -21 +21 @@ Each version of the main AWS CDK library (`aws-cdk-lib`) is compatible with the -Each version of the CDK library may also work with CDK CLI versions older than the version that was current at the time of the CDK library’s release. However, this is not guaranteed. Compatibility depends on the CDK library’s cloud assembly schema version. The AWS CDK generates a cloud assembly during synthesis and the CDK CLI consumes it for deployment. The schema that defines the format of the cloud assembly is strictly specified and versioned. Therefore, an older version of the CDK CLI would need to support the cloud assembly schema version of the CDK library for them to be compatible. +Each version of the AWS Construct Library might also work with AWS CDK Toolkit versions older than the version that was current at the time of the AWS Construct Library’s release. However, this is not guaranteed. Compatibility depends on the AWS Construct Library’s cloud assembly schema version. The AWS CDK generates a cloud assembly during synthesis and the AWS CDK Toolkit consumes it for deployment. The schema that defines the format of the cloud assembly is strictly specified and versioned. Therefore, an older version of the AWS CDK Toolkit would need to support the cloud assembly schema version of the AWS Construct Library for them to be compatible. @@ -23 +23 @@ Each version of the CDK library may also work with CDK CLI versions older than t -When the cloud assembly version required by the CDK library is not compatible with the version supported by the CDK CLI, you receive an error message like the following: +When the cloud assembly version required by the AWS Construct Library is not compatible with the version supported by the AWS CDK Toolkit, you receive an error message like the following: @@ -29 +29 @@ When the cloud assembly version required by the CDK library is not compatible wi -To resolve this error, update the CDK CLI to a version compatible with the required cloud assembly version, or to the latest available version. The alternative (downgrading the construct library modules your app uses) is generally not recommended. +To resolve this error, update the AWS CDK Toolkit to a version compatible with the required cloud assembly version, or to the latest available version. The alternative (downgrading the AWS Construct Library modules your app uses) is generally not recommended. @@ -39 +39 @@ The modules in the AWS Construct Library move through various stages as they are -APIs in the main AWS CDK library, `aws-cdk-lib`, are stable, and the library is fully semantically versioned. This package includes AWS CloudFormation (L1) constructs for all AWS services and all stable higher-level (L2 and L3) modules. (It also includes the core CDK classes like `App` and `Stack`). APIs will not be removed from this package (though they may be deprecated) until the next major release of the CDK. No individual API will ever have breaking changes. When a breaking change is required, an entirely new API will be added. +Except for scenarios where the caveats documented in the next topic apply, APIs in the main AWS Construct Library (`aws-cdk-lib`) are stable, and the library broadly follows semantic versioning principles. The library includes AWS CloudFormation (L1) constructs for all AWS services, which are auto-generated from [CloudFormation resource provider schemas](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/resource-type-schemas.html) and might sometimes include backward incompatible updates. It also includes higher-level (L2 and L3) constructs and the core CDK classes like `App` and `Stack`, which are all stable. APIs will not be removed from this package (though they might be deprecated) until the next major release of the CDK. When a breaking change is required to a stable API, an entirely new API will be added. @@ -44,0 +45,31 @@ When higher-level (L2 or L3) APIs begin to be developed for an AWS service that +## AWS Construct Library semantic versioning clarifications + +While the AWS Construct Library broadly follows semantic versioning principles, there are some important caveats specific to our implementation. In general the AWS Construct Library maintains stability for API consumers, but sometimes adds additional burdens to construct authors to enable the necessary evolution of the framework. + + * **Security impacting changes** + +To meet our security bar, we might be required to change APIs in backward incompatible ways or remove them entirely. This prevents affected APIs from being used and forces implementations to be updated. + + * **Features are described by intent** + +We aim to minimize unexpected changes, but will favor _intent over implementation stability_. The AWS Construct Library does not guarantee that constructs always synthesize to the exact same CloudFormation template or use the exact same set of resources. This especially applies to higher-level constructs, where the same goal can often be achieved in different ways. + + * **Implementing Interfaces and Abstract Classes** + +Interfaces and abstract classes in the AWS Construct Library are stable for **consumers** , but not for **implementors**. This means that you can safely rely on interfaces like `s3.IBucket` to provide at least the same functionality as at the time (AWS Construct Library version) that you started consuming the interface or abstract class. However, periodically, new (abstract) members will be added to interfaces and abstract classes. For anyone **implementing** them, this creates an additional implementation burden to consider when upgrading, since the implementation wouldn’t be implementing the new members yet. Strictly treating additions to interfaces and abstract classes for implementors as breaking changes would unduly limit the evolvability of the AWS Construct Library. In most cases, implementors should prefer to extend concrete classes like `s3.Bucket`. + + * **L1 constructs, generated code, and other APIs marked as external** + +Parts of the AWS Construct Library are generated from data sources coming directly from AWS services. To keep these APIs aligned with reality, generated code might contain backward incompatible changes. Most of the time, data sources are updated to correctly reflect reality and rectify incorrect representation. _Your IDE’s IntelliSense will display external APIs with the`@stability — external` annotation._ + + * **Specific language bindings** + +Language bindings can contain backward incompatible changes in a very limited number of situations. These are caused by upstream type changes that are backward compatible in other supported languages. These types changes are allowed, as doing otherwise would severely limit the evolvability of the library. + +The following list describes all known instances: + + * **Golang - Changing from typed slice to any slice:** A list of a single type is changing to a list of multiple types (union types in TypeScript). In `Go`, these are typed as a slice of any (`*[]any`). Due to Go’s typing assignment rules, changing from `*[]**string** ` to `` is not an automatic conversion. Therefore, this type widening requires consumer code to change. See [Working with any slice](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-go.html#go-cdk-idioms) for strategies. + + + +