Release Phases

Releases, Versioning and Maintenance Phases

Service controllers are built in separate source code repositories. Below, you will find a description of the Project Stages that a service controller repository goes through on its way to being released.

A controller that has reached the RELEASED project stage will have a set of release artifacts, including binary container images for the controller and a Helm Chart that installs the controller into a target Kubernetes cluster. Read more below about our Releases and Versioning policy.

Finally, we have a set of documented Maintenance Phases that clearly outline our support stance for service controllers that have been released.

Project Stages

The controller’s “project stage” describes how far along the controller is towards being released:

PROPOSED -> PLANNED -> IN PROGRESS -> RELEASED

PROPOSED

The PROPOSED stage indicates that there is expressed interest in supporting an AWS service in ACK.

At this stage, there will be a Github Issue and/or a Github Project for tracking the creation of the ACK service controller for the service.

The GitHub Issue WILL NOT be associated with a GitHub Milestone.

PLANNED

The PLANNED stage indicates that we plan to make a controller for this service available in ACK.

At this stage, there WILL BE a GitHub Milestone that tracks progress towards the release of the controller.

IN PROGRESS

The IN PROGRESS stage indicates that the ACK service controller for the AWS service is actively being built in preparation for a release of that ACK service controller.

In the IN PROGRESS stage we identify those AWS service API resources that will be supported by the controller and generate the code that manages the lifecycle of these resources.

What do we mean by ‘AWS service API resources’?
An AWS service API resource is a top-level object that can be created by a particular AWS service API. For example, an SNS Topic or an S3 Bucket. Some service APIs have multiple top-level resources; SNS, for instance, has Topic, PlatformApplication and PlatformEndpoint top-level resources that may be created.

RELEASED

The RELEASED project stage indicates that the ACK service controller source repository has had a Semantic Versioning Git tag applied and that both a container image and Helm Chart have been built and published to the ECR Public repositories for ACK.

Once a service controller reaches the RELEASED project stage, that does not mean that there can never be any changes or additions to the Custom Resource Definitions (CRDs) or public interfaces exposed by that service controller. The RELEASED project stage is simply an indication that there is at least one SemVer-tagged binary release of the controller.

Consumers should look to the SemVer release tag as an indication of whether code included in that release introduces new breaking (major version increment) or non-breaking features (minor version increment) or simply bug fixes (patch version increment). Consumers should see release notes for a release tag for a full description of changes included in that release.

Releases and Versioning

Important
ACK does not have a single release status or version. Different components within the ACK project have different release cadences, versions and statuses. Please read the information below before installing any ACK component.

Service controllers in ACK use Semantic Versioning to indicate whether changes included in a particular binary release introduce features or bug fixes and whether or not features break backwards compatibility for public APIs and interfaces.

There are two release artifacts produced when an ACK service controller is released: a binary container image with the controller and a Helm Chart that installs the controller into a target Kubernetes cluster. Both these artifacts will have tags that correspond to the Semantic Version Git tag applied against the source code repository for the controller.

Semantic Versioning

ACK is a collection of custom Kubernetes controllers, one for each supported AWS API. Each ACK controller is composed of an ACK common runtime and Go code that links the Kubernetes API and the AWS API. Much of this Go code is generated by the ack-generate tool; some of the Go code is hand-crafted.

All code components in ACK use Semantic Versioning (SemVer) as a signal to consumers whether public interfaces or APIs have breaking changes.

When an ACK component is released, a Git tag containing a SemVer (X.Y.Z) is created on the component’s source repository. If the commits to the source repository in between the last Git tag and the commit being tagged have introduced changes that break public-facing APIs or interfaces, the SemVer will have its major version (“X”) incremented. If the commits introduce functionality that does not break interfaces or APIs, the minor version (“Y”) will be incremented. If the commits simply fix bugs and do not introduce any features or interface changes, the patch version (“Z”) will be incremented.

Releases of any ACK component that have a zero major release number (e.g. 0.0.2) may have breaking changes to the public API or interfaces exposed by that component.

This is by design, and per the Semantic Versioning specification:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

For ACK components that have a binary distributable – i.e. a container image – the creation of a new SemVer Git tag on the source code repository triggers the automatic building and publishing of a container image with an image tag including the SemVer version.

For example, if a Git tag of v1.2.6 was created on the github.com/aws-controllers-k8s/s3-controller repository, a container image with a tag 1.2.6 would be published to the public.ecr.aws/aws-controllers-k8s/s3-controller ECR Public repository.

Note
Binaries for individual ACK service controllers components are published in separate Amazon ECR Public repositories.

For ACK components that have a Helm Chart distributable – i.e. an ACK service controller – the creation of a new SemVer Git tag on the source code repository triggers automatic building and publishing of a Helm Chart with an artifact tag including the SemVer version.

For example, a Git tag of v1.2.6 on the github.com/aws-controllers-k8s/s3-controller repository means a Helm chart with a tag 1.2.6 would be published to the public.ecr.aws/aws-controllers-k8s/s3-chart ECR Public repository.

A Word About Dependencies

Each service-specific ACK controller – e.g. the ElastiCache ACK controller – depends on a specific version of the ACK common runtime. This dependency is specified in the controller’s go.mod file.

The ACK code generator that produces Go code for service controllers depends on a specific version of the ACK common runtime.

Dependency between the code generator and common runtime
The ACK code generator depends on the ACK common runtime in a unique way: the Go code that the ACK code generator produces adheres to a specific version of the ACK common runtime. Even though no Go code in the ACK code generator actually imports the ACK common runtime, this dependency exists because the Go code produced by the templates inside the code generator imports the ACK common runtime. In order to make this Go code dependency more strict, we have a test package inside the ACK code generator that imports the ACK common runtime. In this way, we’re able to include a version-specific dependency line in the ACK code generator’s go.mod file, thereby allowing Go’s module infrastructure to pin the dependency between the code generator and the common runtime.

Maintenance Phases

As noted above, individual ACK service controllers all use Semantic Versioning (“X.Y.Z”) in order to signal breaking interface changes. However, each controller follows its own release cadence and each controller has a separate team of contributors that maintain the code, test the controller and determine whether the controller is stable in long-running operation.

ACK service controllers having release tags within a major Semantic Version (“X”) will be in one of four Maintenance Phases:

Preview

ACK controllers in the Preview Maintenance Phase are released for testing by users and are not recommended for production use.

For Preview controllers, we ask users to submit bug reports using Github Issues and we will do our best to remediate problems in a timely manner.

General Availability

ACK controllers in the General Availability (GA) Maintenance Phase have been through long-running “soak” tests and are recommended for production use by the team maintaining that controller.

All ACK controllers in the General Availability Maintenance Phase will have a Helm Chart tagged with the major version >0 (eg. 1.0.0).

Users who submit bug reports using Github Issues that reference a General Availability controller will have their bug reports prioritized by the contributor team maintaining that controller.

Deprecated

ACK controllers in the General Availability Maintenance Phase may move to a Deprecated Maintenance Phase after a Deprecation Warning notice has been sent out (and the controller’s documentation has been updated with said deprecation notice).

Controllers in Deprecated Maintenance Phase continue to receive the same level of support as controllers in the General Availability phase.

Not Supported

ACK controllers may eventually be moved into a Not Supported Maintenance Phase.

A controller major version series may move from the Preview Maintenance Phase to the Not Supported Maintenance Phase at any time. This may happen if the team maintaining the controller determines it is not possible to get the controller with that major version series into a General Availability phase.

A controller major version series may move from the Deprecated Maintenance Phase to the Not Supported Maintenance Phase only after a 1-year deprecation period has elapsed.

Edit this page on GitHub