Turbot Version Release Schedule & Change Process

Introduction

Turbot provides customers with a single, integrated approach to Software Defined Operations. Building on a range of highly dynamic ecosystems and vendors requires Turbot to be continuously improving to integrate their features. Because Turbot aims to provide a cohesive, integrated solution this means that Turbot itself needs to evolve.

Change in Turbot is communicated through semantic versioning, scheduled major versions and a carefully designed & communicated change process.

Release frequency

Turbot does not provide a fixed date for releases, but targets the following approximate schedule:

  • Major versions - Quarterly.
  • Minor versions - Every 1-2 weeks.
  • Patch versions - On demand for critical bug fixes to minor versions.

Turbot focuses our work on a single development stream. Every release moves forward from the latest version (e.g. 2.3.0), except for extreme circumstances where a patch may be released to a prior (major) version (e.g. 1.8.3).

API Changes

The Turbot API changes over time. Changes are made in line with semantic versioning conventions, and managed to reduce negative impact on customers. (Although other services lock their APIs, Turbot requires evolution in our quest to provide an integrated, best practice approach to a wide, fast-moving ecosystem of tools.)

Bottom line - APIs remain constant as long as possible. When necessary, API deprecation is clearly communicated over a full major version cycle.

With regard to semantic versioning, API changes are managed as follows:

  • Patch version:
    • May fix unexpected behavior in existing APIs.
  • Minor version:
    • As for patch versions; plus
    • May add new input or output fields to existing APIs.
    • May add new API endpoints.
    • May deprecate an existing API. Example: In v1.2.0 the API /api/v1/my-ok-api is replaced by a new endpoint /api/v1/my-great-api and the old API /api/v1/my-ok-api is marked as deprecated. Per below, the old API /api/v1/my-ok-api must be deprecated for a full major version (v2) before it is may be removed (v3).
    • May deprecate an input parameter to an existing API.
    • May deprecate an output field from an existing API.
  • Major version:
    • As for minor versions; plus
    • May remove an existing deprecated API, but only if it has been deprecated for a full major version cycle.
    • May remove a deprecated input parameter to an existing API, but only if it has been deprecated for a full major version cycle.
    • May remove a deprecated output parameter to an existing API, but only if it has been deprecated for a full major version cycle.

Turbot provides API access under versioned endpoints, e.g. /api/v1/api/v2, etc. Each version endpoint supports all APIs available at that version, including those that are deprecated. For example, a v2 API called /api/v2/my-api is changed to deprecated but still available as/api/v3/my-api before no longer being available as /api/v4/my-api.

While the endpoint version moves forward, Turbot continues to support previous endpoint versions wherever possible. For example, in v5 of Turbot there may still be support for /api/v1/old-reliable-api, but if v5 of Turbot will not work for an API removed in v3 such as/api/v3/api-deprecated-in-v2-and-removed-in-v3.

Calls to deprecated APIs are logged and return a warning header. This allows the caller to detect the problem, and allows Turbot Administrators to identify use of deprecated APIs before upgrade.

Option Names

Like APIs, Options are a key configuration point for customers and change is carefully managed in Turbot.

  • Patch version:
    • May fix option names or values.
  • Minor version:
    • As for patch versions; plus
    • May add a new option.
    • May add a new value to an existing option.
    • May deprecate an existing option.
    • May deprecate an existing option value.
    • May move the target level to a lower level target that is not at a different permission level, e.g., AWS Account->AWS IAM User.
  • Major version:
    • As for minor versions; plus
    • May remove a deprecated option, but only if it has been deprecated for a full major version cycle.
    • May remove a deprecated option value, but only if it has been deprecated for a full major version cycle.
    • May change a default value to an existing option. No deprecation cycle is possible in this case, so customers are notified of this change with information about settings to maintain current behavior.
    • May move the target level to a lower level target that is at a different permission level, e.g., Cluster->Account.
    • May move the target level to a higher level target, e.g., AWS IAM User->AWS Account.

Rights

Like APIs, Rights are a key configuration point for customers and change is carefully managed in Turbot.

  • Patch version:
    • May fix issues with Right names.
    • May fix issues with permission scope of Rights.
  • Minor version:
    • As for patch versions; plus
    • May add new rights.
    • May update permission scope of rights, but only within appropriate intent of the Right. For example, AWS/EC2/Metadata permissions may be expanded to include new EC2 functionality for accessing metadata.
    • May deprecate an existing right.
  • Major version:
    • As for minor versions; plus
    • May remove a deprecated right, but only if it has been deprecated for a full major version cycle.

Stack Engines (e.g. Ansible, Terraform)

Turbot supports multiple versions of stack engines simultaneously, giving our customers a lot of flexibility for development of their own scripts. But, these dependencies need to be managed in Turbot and also moved forward on a predictable schedule.

Turbot accumulates stack engine versions over time, and cleans them out with each Turbot major version. Specifically, with every Turbot minor release we add the latest version of each supported stack engine major version. For example, in Turbot v2.3.0 we’d ensure we had the latest version of Ansible 1.x, Ansible 2.x, Terraform 0.x and Terraform 1.x.

Deprecation of stack engines is done as follows:

  • Stack engine major version. Based on customer usage, Turbot will usually support older major versions of stack engines for a long time. To be removed, they must be marked as deprecated for at least one Turbot major version cycle.
  • Stack engine minor version. Minor versions must be marked deprecated for at least one Turbot major version cycle before being removed.
  • Stack engine patch version. Old stack engine patch versions are deprecated as soon as a new version is added to Turbot. For example, if Terraform 1.2.3 is added in Turbot 2.3.0 then Terraform 1.2.2 is immediately marked as deprecated. All deprecated patch versions will be removed in the next major version. For example, Turbot 3.0.0 would bring forward Terraform 1.2.4, but remove Terraform 1.2.0, 1.2.1, 1.2.2 and 1.2.3.

 

Questions

As always, please address any questions, concerns or comments to Turbot Support.

Was this article helpful?
0 out of 0 found this helpful