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.
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
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.
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 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 v1.2.6 would be published to the
public.ecr.aws/aws-controllers-k8s/s3-controller ECR Public
repository.
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 v1.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.
go.mod file, thereby allowing
Go’s module infrastructure to pin the dependency between the code generator and
the common runtime.Stable Helm Charts
Some ACK service controllers will have Helm Charts with a
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 full
stable artifact tag for the ElastiCache ACK service controller’s “v1” major
version series would be
public.ecr.aws/aws-controllers-k8s/elasticache-chart:v1-stable.
This stable artifact tag points to a Helm chart that has configuration values
that have been tested with a specific SemVer container 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.
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
container 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
public.ecr.aws/aws-controllers-k8s/elasticache-controller image tagged with
the 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/elasticache-controller:v1.2.6.
They then package the Helm Chart and publish it as an OCI Artifact to the
public.ecr.aws/aws-controllers-k8s/elasticache-chart registry, using an OCI
artifact tag of 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/elasticache-controller:v1.3.2. They would
then package this Helm Chart and push overwrite the
public.ecr.aws/aws-controllers-k8s/elasticache-chart: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.