Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moved upgrade from FAQ to upgrade guide #1545

Merged
merged 3 commits into from
Mar 25, 2022
Merged

Moved upgrade from FAQ to upgrade guide #1545

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1e73df6
Moved upgrade from FAQ to upgrade guide
chrisnegus Mar 18, 2022
0b123ac
Responded to PR comments
chrisnegus Mar 21, 2022
7c9e0e2
Merge branch 'main' into review-upgrade-guide
chrisnegus Mar 25, 2022
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
8 changes: 1 addition & 7 deletions website/content/en/preview/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,10 +141,4 @@ See [Deprovisioning nodes]({{< ref "./tasks/deprovisioning" >}}) for information

## Upgrading
### How do I upgrade Karpenter?
Karpenter is a controller that runs in your cluster, but it is not tied to a specific Kubernetes version, as the Cluster Autoscaler is.
Use your existing upgrade mechanisms to upgrade your core add-ons in Kubernetes and keep Karpenter up to date on bug fixes and new features.

Karpenter requires proper permissions in the `KarpenterNode IAM Role` and the `KarpenterController IAM Role`.
To upgrade Karpenter to version `$VERSION`, make sure that the `KarpenterNode IAM Role` and the `KarpenterController IAM Role` have the right permission described in `https://karpenter.sh/$VERSION/getting-started/getting-started-with-eksctl/cloudformation.yaml`.
Next, locate `KarpenterController IAM Role` ARN (i.e., ARN of the resource created in [Create the KarpenterController IAM Role](../getting-started/getting-started-with-eksctl/#create-the-karpentercontroller-iam-role)) and the cluster endpoint, and pass them to the helm upgrade command
{{% script file="./content/en/preview/getting-started/getting-started-with-eksctl/scripts/step08-apply-helm-chart.sh" language="bash"%}}
For information on upgrading Karpenter, see the [Upgrade Guide]({{< ref "./upgrade-guide/" >}})a.
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved
69 changes: 36 additions & 33 deletions website/content/en/preview/upgrade-guide/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,32 @@ linkTitle: "Upgrade Guide"
weight: 10
---

# Compatible Dependents
Karpenter is a controller that runs in your cluster, but it is not tied to a specific Kubernetes version, as the Cluster Autoscaler is.
Use your existing upgrade mechanisms to upgrade your core add-ons in Kubernetes and keep Karpenter up to date on bug fixes and new features.

To make upgrading easier we aim to minimize introduction of breaking changes with the followings:
This document describes issues related to upgrading Karpenter, along with steps you can follow to perform an upgrade.
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved

1. Provisioner API
2. Helm Chart
# Compatibility issues

When we introduce a breaking change, we do so only in as described in this document.
To make upgrading easier, we aim to minimize the introduction of breaking changes with the followings components:

## What We Keep Compatible
* Provisioner API
* Helm Chart

2. The application itself
3. The documentation of the application
We try to maintain compatibility with:

## When Do We Break Compatibility?
* The application itself
* The documentation of the application

According to [Semantic Versioning 2.0.0](https://semver.org/) which Karpenter follows in our release versions, while in
major version zero (v0.y.z) [anything may change at any time](https://semver.org/#spec-item-4). However, to further
protect our customers during this phase we will only introduce breaking changes in minor releases (releases that
increment y in x.y.z). Note this does not mean every minor upgrade has a breaking change as we will also increment the
When we introduce a breaking change, we do so only as described in this document.

Karpenter follows [Semantic Versioning 2.0.0](https://semver.org/) in its release versions, while in
major version zero (v0.y.z) [anything may change at any time](https://semver.org/#spec-item-4).
However, to further protect customers during this phase we will only introduce breaking changes in minor releases (releases that increment y in x.y.z).
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved
Note this does not mean every minor upgrade has a breaking change as we will also increment the
minor version when we release a new feature.

The users should therefore check to see if there is breaking change, every time they are upgrading to a new minor
version.
Users should therefore check to see if there is a breaking change every time they are upgrading to a new minor version.

## How Do We Break Incompatibility?

Expand All @@ -36,38 +38,39 @@ When there is a breaking change we will:
* Increment the minor version when in major version 0
* Add a permanent separate file named `migrating_to_vx.y.z.md` to our website (linked at the bottom of this page)
clearly explaining the breaking change and what needs to be done on the customer side to ensure a safe upgrade
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved
* Add the sentence “This is a breaking change, please refer to `migrating_to_x.y.z.md` for upgrade instructions” to the
top of the release notes and in all our announcements
* Add the sentence “This is a breaking change, please refer to `migrating_to_x.y.z.md` for upgrade instructions” to the top of the release notes and in all our announcements

## How Do We Find Incompatibilities

Besides the peer review process for all changes to the code base we also do the followings in order to find
incompatibilities:
* (To be implemented) Automated tests to see if installing, uninstalling, upgrading from an older version and downgrading
to an older version to check the compatibility of the application
* (To be implemented) Turn the commands in our
documentation into scripts that we can automatically run to find incompatibilities between the application and
documentation
* (To be implemented) Automated tests for installing, uninstalling, upgrading from an older version, and downgrading to an older version to check the compatibility of the application
* (To be implemented) Turn the commands in our documentation into scripts that we can automatically run to find incompatibilities between the application and documentation
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved

## Nightly Builds

(To be implemented) Every night we will build and release everything that has been checked into the source code. This
allows us to detect problems including breaking changes and potential drifts in our external dependencies sooner than we
otherwise would. It also allows some of advanced users who have their own nightly builds to test the upcoming changes
before they are released.
(To be implemented) Every night we will build and release everything that has been checked into the source code.
This allows us to detect problems including breaking changes and potential drifts in our external dependencies sooner than we otherwise would.
It also allows some of advanced users who have their own nightly builds to test the upcoming changes before they are released.
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved

## Release Candidates

(To be implemented) We are considering having release candidates when we are in major version 1. By adopting this
practice we allow our users who are early adopters to test out new releases before they are available to the wider
community thereby providing us with early feedback which would result in more stable releases.
(To be implemented) We are considering having release candidates when we are in major version 1.
By adopting this practice we allow our users who are early adopters to test out new releases before they are available to the wider community thereby providing us with early feedback which would result in more stable releases.
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved

## Security Patches

While we are in major version 0 we will not release security patches to older versions, rather we provide the patches in
the latest versions. When at major version 1 we will have an EOL (end of life) policy where we provide security patches
While we are in major version 0 we will not release security patches to older versions.
Rather we provide the patches in the latest versions.
When at major version 1 we will have an EOL (end of life) policy where we provide security patches
for a subset of older versions and deprecate the others.

# Released Upgrade Notes
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved
# Steps

Upgrading your version of Karpenter requires that you:
chrisnegus marked this conversation as resolved.
Show resolved Hide resolved

There are no published upgrade notes yet.
1. Set proper permissions in the `KarpenterNode IAM Role` and the `KarpenterController IAM Role`.
To upgrade Karpenter to version `$VERSION`, make sure that the `KarpenterNode IAM Role` and the `KarpenterController IAM Role` have the right permission described in `https://karpenter.sh/$VERSION/getting-started/getting-started-with-eksctl/cloudformation.yaml`.
1. Locate `KarpenterController IAM Role` ARN (i.e., ARN of the resource created in [Create the KarpenterController IAM Role](../getting-started/getting-started-with-eksctl/#create-the-karpentercontroller-iam-role)) and the cluster endpoint.
1. Pass that information to the helm upgrade command
{{% script file="./content/en/preview/getting-started/getting-started-with-eksctl/scripts/step08-apply-helm-chart.sh" language="bash"%}}