Skip to content
This repository was archived by the owner on May 12, 2021. It is now read-only.

Document compatibility of component versions #191

Closed
jodh-intel wants to merge 4 commits into from
Closed

Document compatibility of component versions #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
723386c
docs: Move Components section next to Versions section
Jul 5, 2018
adccf50
docs: Document compatibility of component versions
Jul 5, 2018
48cc415
docs: Refer to Component version compatibility
Jul 5, 2018
b9144b7
docs: Add missing title to dev guide
Jul 5, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions Developer-Guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# Kata Containers Developer Guide

* [Warning](#warning)
* [Assumptions](#assumptions)
* [Initial setup](#initial-setup)
* [Requirements to build individual components](#requirements-to-build-individual-components)
* [Individual component compatibility](#individual-component-compatibility)
* [Build and install the Kata Containers runtime](#build-and-install-the-kata-containers-runtime)
* [Check hardware requirements](#check-hardware-requirements)
* [Configure to use initrd or rootfs image](#configure-to-use-initrd-or-rootfs-image)
Expand Down Expand Up @@ -75,6 +78,22 @@ You need to install the following to build Kata Containers components:
- `make`.
- `gcc` (required for building the shim and runtime).

# Individual component compatibility

Using versions of individual components newer than the last official released
version might result in
[compatibility issues](Releases.md#component-version-compatibility).

If you have only updated a subset of the Kata components and notice strange
behavior, we recommend you update the remaining components to ensure you are
using the latest versions of all of them. Also, remember to
[create a new image containing the latest agent version](#create-and-install-rootfs-and-initrd-image).

If you still have compatibility issues after following the previous
instructions, refer to the
[troubleshooting section](#troubleshoot-kata-containers) and
[get in contact with us](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#contact).

# Build and install the Kata Containers runtime

```
Expand Down
32 changes: 23 additions & 9 deletions Releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
* [Introduction](#introduction)
* [Versioning](#versioning)
* [Tagging repositories](#tagging-repositories)
* [Components](#components)
* [Component version compatibility](#component-version-compatibility)
* [Tagging repositories](#tagging-repositories)
* [Release checklist](#release-checklist)
* [Release process](#release-process)

Expand Down Expand Up @@ -34,6 +35,27 @@ Semantic versioning is used since the version number is able to convey clear inf

A major release will also likely require a change of the container manager version used, for example Docker\*. Please refer to the release notes for further details.

## Components

A new release results in all Kata components being given a new
[version](#versioning), even if there are no changes to that component since
the last version. The version for a release is **identical** for all
components.

This strategy allows diagnostic tools such as `kata-runtime kata-env` to record full version details of all components to help with problem determination.

Note that although hypervisor and guest kernel both have versions, these are not updated for new releases as they are not core components developed by the Kata community.

### Component version compatibility

Semantic versioning allows users to determine how a new version of a
particular component relates to the previous version of that component.
However, it is not possible to compare two *different* Kata component
Copy link
Copy Markdown
Contributor

@grahamwhaley grahamwhaley Jul 5, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain or expand on why it is 'not possible to compare...' - it's not quite clear to me here what you are trying to explain.

Copy link
Copy Markdown
Author

@jodh-intel jodh-intel Jul 6, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nor me! 😄

I think we're all struggling to really understand what this actually means, but I'm trying to find words, so if you can suggest some based on what follows, I'm all ears! ;)

It's rather difficult to write this. What I'm trying to state is that although we "use" semver for each component, since we require all components to have the same version to be compatible, we require our own... cough.. interpretation of what semver means. It could be argued that semver is implicitly only meant for comparing versions of the same component.

However since we're imposing the extra requirement that all components need to be upgraded in lock-step (all components having the same version), a gRPC protocol change (what would nominally be an "API breakage" for a single component) for example can be handled by a MINOR version number change only (since this detail is invisible to the user assuming they upgrade all components in lock-step).

For example, if the proxy is at version 1.2.0 but the other components are all at 1.1.0, there are no guarantees the system will work.

I'll also probably add words based on @gnawux's comments to the ML (http://lists.katacontainers.io/pipermail/kata-dev/2018-June/000232.html) too.

Copy link
Copy Markdown
Member

@egernst egernst Jul 23, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but 1.1.1 and 1.1.0 should be fine. Right?

Copy link
Copy Markdown
Author

@jodh-intel jodh-intel Jul 24, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@grahamwhaley, @egernst - should we just drop the "Component version compatibility" section entirely then do you think?

Copy link
Copy Markdown
Author

@jodh-intel jodh-intel Jul 30, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-ping @grahamwhaley, @egernst.

Copy link
Copy Markdown
Author

@jodh-intel jodh-intel Aug 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts guys...? :)

Copy link
Copy Markdown
Contributor

@grahamwhaley grahamwhaley Aug 6, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @jodh-intel - I'm prone to put this PR on hold, pretty much just due to this semver related section, until we have the Kata versioning and release flow defined - and then we can reference that.
I believe @jcvenegas is planning a first draft around releases, versioning and backport/lifetimes - let's wait for that.
As such, I'm going to mark this PR as WIP, just to make it clear it is pending an update.

versions, even though all component versions are changed together.

To ensure compatibility it is necessary to always use components of the same
version.

## Tagging repositories

To create a signed and annotated tag for a repository, first ensure that `git(1)` is configured to use your `gpg(1)` key:
Expand All @@ -55,14 +77,6 @@ The annotation text must conform to the usual [patch format rules](https://githu
- The subsystem must be "`release: $tag`".
- The body of the message must contain details of changes in the release in `git-shortlog(1)` format.

## Components

A new release will result in all Kata components being given a new [version](#versioning), even if no changes were made to that component since the last version. The version for a release is **identical** for all components.

This strategy allows diagnostic tools such as `kata-runtime kata-env` to record full version details of all components to help with problem determination.

Note that although hypervisor and guest kernel both have versions, these are not updated for new releases as they are not core components developed by the Kata community.

## Release checklist

The detailed steps to follow to create a new release are specified in the [Release Checklist](Release-Checklist.md).
Expand Down
3 changes: 2 additions & 1 deletion Upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,8 @@ As shown in the
[installation instructions](https://github.com/kata-containers/documentation/blob/master/install),
Kata Containers provide binaries for popular distributions in their native
packaging formats. This allows Kata Containers to be upgraded using the
standard package management tools for your distribution.
standard package management tools for your distribution and also guarantees
[component version compatibility](Releases.md#component-version-compatibility).

# Appendices

Expand Down