Skip to content

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 Docker 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.

!!! note "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 Docker 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 Docker 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.

Service controllers may have a Stable Helm Chart that will install a version of the service controller binary that the maintainer team is confident will hold up to production use.

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. v0.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 Docker image -- the creation of a new SemVer Git tag on the source code repository will trigger automatic building and publishing of a Docker 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 Docker image with a tag s3-v1.2.6 would be published to the aws-controllers-k8s/controller ECR repository.

Note

Binaries for ACK components are published in our Amazon ECR Public registry.

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 will trigger 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 s3-v1.2.6 would be published to the aws-controllers-k8s/chart ECR 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.

Stable Helm Charts

Tip

We recommend using Helm to install an ACK service controller.

Some ACK service controllers will have Helm Charts with a $SERVICE-v$MAJOR_VERSION-stable tag, referred from here out as just a "stable artifact tag". There will only be one of these tags for the ACK service controller in a major version series. For example, the stable artifact tag for the ElastiCache ACK service controller's "v1" major version series would be elasticache-v1-stable.

This stable artifact tag points to a Helm chart that has configuration values that have been tested with a specific SemVer Docker image. Typically these tests are "soak" tests and allow the team maintaining that ACK controller's source code to have a high degree of confidence in the controller's long-running operation.

Note

Please note that not all ACK service controllers will have a Helm chart with a stable artifact tag. Furthermore, there will only ever be a single stable Helm Chart tag per major version series of a controller.

This stable Helm Chart tag (an OCI Artifact tag) will point to different Helm Chart packages over time. From time to time, the maintainer team for a service controller may update the configuration values and associated SemVer Docker image tag for the controller binary to point to a newer image.

For example, consider the ElastiCache ACK service controller maintainer team has executed a series of long-running tests of the controller image tagged with the elasticache-v1.2.6 SemVer tag. The maintainer team is confident that the controller is stable for production use. In the stable Git branch of the ElastiCache service controller's source repository, the team would update the Helm Chart's Deployment, setting the Deployment.spec.template.spec.containers[0].image to public.ecr.aws/aws-controllers-k8s/controller/elasticache-v1.2.6.

They then package the Helm Chart and publish it as an OCI Artifact to the public.ecr.aws/aws-controllers-k8s/chart registry, using an OCI artifact tag of elasticache-v1-stable.

A couple months later, the maintainer team has added a few minor, non-breaking features to their controller along with a number of bug fixes. The latest SemVer tag for the ElastiCache controller image is at v1.3.9.

The maintainer team has separately been executing long-running tests against the v1.3.2 controller image and are confident that this release is appropriate for production use. The maintainer team would update the Helm Chart in their stable Git branch to have its Deployment.spec.template.spec.containers[0].image set to public.ecr.aws/aws-controllers-k8s/controller/elasticache-v1.3.2. They would then package this Helm Chart and push overwrite the public.ecr.aws/aws-controllers-k8s/chart:elasticache-v1-stable OCI Artifact tag to point to this newly-updated Helm Chart that refers to the v1.3.2 controller image.

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 with the stable artifact tag.

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.