knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve upgrade docs (#3515) 

* Improve upgrade docs

* clean up docs order, prereqs

* minor typo

* Update docs/upgrade/upgrade-installation-with-operator.md

* Update docs/upgrade/upgrade-installation-with-operator.md

* Update docs/upgrade/upgrade-installation-with-operator.md
This commit is contained in:
Ashleigh Brennan 2021-04-30 18:36:56 -05:00 committed by GitHub
parent b39d59a289
commit 354f47dbee
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 175 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/client/_index.md
View File

@ -1,6 +1,6 @@
---
title: "CLI tools"
weight: 03
weight: 04
type: "docs"
showlandingtoc: "false"
aliases:

2
docs/eventing/_index.md
View File

@ -1,6 +1,6 @@
---
title: "Knative Eventing"
weight: 05
weight: 06
type: "docs"
showlandingtoc: "false"
aliases:

201
docs/install/upgrade-installation-with-operator.md
View File

@ -1,201 +0,0 @@
---
title: "Upgrading your installation with Knative operator"
weight: 21
type: "docs"
---
The Knative operator supports a straightforward upgrade process. It supports upgrading the Knative component
by a single [minor](https://semver.org/) version number. For example, if you have v0.17 installed, you must upgrade to
v0.18 before attempting to upgrade to v0.19. The attribute `spec.version` is the only field you need to change in the
Serving or Eventing CR to perform an upgrade. You do not need to specify the version in terms of the `patch` number,
because the Knative Operator will match the latest available `patch` number, as long as you specify `major.minor` for
the version. For example, you only need to specify `0.19` to upgrade to the latest v0.19 release. There is no need to
know the exact `patch` number.
The Knative Operator implements a minus 3 principle to support the Knative versions, which means the current version
of the Operator can support Knative with the version back 3 in terms of the `minor` number. For example, if the
current version of the Operator is 0.19.x, it bundles and supports the installation of Knative with the versions,
0.16.x, 0.17.x, 0.18.x and 0.19.x.
## Before you begin
Knative Operator maximizes the automation for the upgrade process, all you need to know is the current version of your
Knative, the target version of your Knative, and the namespaces for your Knative installation. In the
following instruction, Knative Serving and the Serving custom resource are installed in the `knative-serving` namespace,
and Knative Eventing and the Eventing custom resource are installed in the `knative-eventing` namespace.
### Check the current version of the installed Knative
If you want to check the version of the installed Knative Serving, you can apply the following command:
```
kubectl get KnativeServing knative-serving --namespace knative-serving
```
If your current version for Knative Serving is 0.19.x, you will get the result as below:
```
NAME VERSION READY REASON
knative-serving 0.19.0 True
```
As Knative only supports the upgrade with one single `minor` version, the target version is 0.20 for Knative Serving.
The status `True` means the Serving CR and Knative Serving are in good status.
If you want to check the version of the installed Knative Eventing, you can apply the following command:
```
kubectl get KnativeEventing knative-eventing --namespace knative-eventing
```
If your current version for Knative Eventing is 0.19.x, you will get the result as below:
```
NAME VERSION READY REASON
knative-eventing 0.19.0 True
```
As Knative only supports the upgrade with one single `minor` version, the target version is 0.20 for Knative Eventing.
The status `True` means the Eventing CR and Knative Eventing are in good status.
## Performing the upgrade
To upgrade, apply the Operator CRs with the same spec, but a different target version for the attribute `spec.version`.
If your existing Serving CR is as below:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
name: knative-serving
namespace: knative-serving
spec:
version: "0.19"
```
then apply the following CR to upgrade to 0.20:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
name: knative-serving
namespace: knative-serving
spec:
version: "0.20"
```
If your existing Eventing CR is as below:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeEventing
metadata:
name: knative-eventing
namespace: knative-eventing
spec:
version: "0.19"
```
then apply the following CR to upgrade to 0.20:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeEventing
metadata:
name: knative-eventing
namespace: knative-eventing
spec:
version: "0.20"
```
## Verifying the upgrade
To confirm that your Knative components have successfully upgraded, view the status of their pods in the relevant namespaces.
All pods will restart during the upgrade and their age will reset.
If you upgraded Knative Serving and Eventing, enter the following commands to get information about the pods for each namespace:
```bash
kubectl get pods --namespace knative-serving
```
```bash
kubectl get pods --namespace knative-eventing
```
These commands return something similar to:
```bash
NAME READY STATUS RESTARTS AGE
activator-6875896748-gdjgs 1/1 Running 0 58s
autoscaler-6bbc885cfd-vkrgg 1/1 Running 0 57s
autoscaler-hpa-5cdd7c6b69-hxzv4 1/1 Running 0 55s
controller-64dd4bd56-wzb2k 1/1 Running 0 57s
istio-webhook-75cc84fbd4-dkcgt 1/1 Running 0 50s
networking-istio-6dcbd4b5f4-mxm8q 1/1 Running 0 51s
storage-version-migration-serving-serving-0.20.0-82hjt 0/1 Completed 0 50s
webhook-75f5d4845d-zkrdt 1/1 Running 0 56s
```
```bash
NAME READY STATUS RESTARTS AGE
eventing-controller-6bc59c9fd7-6svbm 1/1 Running 0 38s
eventing-webhook-85cd479f87-4dwxh 1/1 Running 0 38s
imc-controller-97c4fd87c-t9mnm 1/1 Running 0 33s
imc-dispatcher-c6db95ffd-ln4mc 1/1 Running 0 33s
mt-broker-controller-5f87fbd5d9-m69cd 1/1 Running 0 32s
mt-broker-filter-5b9c64cbd5-d27p4 1/1 Running 0 32s
mt-broker-ingress-55c66fdfdf-gn56g 1/1 Running 0 32s
storage-version-migration-eventing-0.20.0-fvgqf 0/1 Completed 0 31s
sugar-controller-684d5cfdbb-67vsv 1/1 Running 0 31s
```
You can also verify the status of Knative by checking the CRs:
```bash
kubectl get KnativeServing knative-serving --namespace knative-serving
```
```bash
kubectl get KnativeEventing knative-eventing --namespace knative-eventing
```
These commands return something similar to:
```
NAME VERSION READY REASON
knative-serving 0.20.0 True
```
```
NAME VERSION READY REASON
knative-eventing 0.20.0 True
```
## Rollback
If the upgrade fails, you can always have a rollback solution to restore your Knative to the current version. If your
current version is 0.19, you can apply the following CR to restore Knative Serving and Eventing.
For Knative Serving:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
name: knative-serving
namespace: knative-serving
spec:
version: "0.19"
```
For Knative Eventing:
```
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeEventing
metadata:
name: knative-eventing
namespace: knative-eventing
spec:
version: "0.19"
```

2
docs/knative-offerings.md
View File

@ -1,7 +1,7 @@
---
title: "Knative Offerings"
linkTitle: "Knative Offerings"
weight: 06
weight: 07
type: "docs"
---

2
docs/serving/_index.md
View File

@ -1,6 +1,6 @@
---
title: "Knative Serving"
weight: 04
weight: 05
type: "docs"
showlandingtoc: "false"
---

35
docs/upgrade/_index.md Normal file
View File

@ -0,0 +1,35 @@
---
title: "Upgrading Knative"
weight: 03
type: "docs"
---
Knative supports upgrading by a single [minor](https://semver.org/) version number. For example, if you have v0.20.0 installed, you must upgrade to v0.21.0 before attempting to upgrade to v0.22.0.
To verify the version of your current Knative installation:
- Check the installed **Knative Serving** version by entering the following command:
```bash
kubectl get KnativeServing knative-serving --namespace knative-serving
```
Example output:
```bash
NAME VERSION READY REASON
knative-serving 0.21.0 True
```
- Check the installed **Knative Eventing** version by entering the following command:
```bash
kubectl get KnativeEventing knative-eventing --namespace knative-eventing
```
Example output:
```bash
NAME VERSION READY REASON
knative-eventing 0.21.0 True
```

122
docs/upgrade/upgrade-installation-with-operator.md Normal file
View File

@ -0,0 +1,122 @@
---
title: "Upgrading using the Knative Operator"
weight: 21
type: "docs"
aliases:
- /docs/install/upgrade-installation-with-operator
---
The attribute `spec.version` is the only field you need to change in the
Serving or Eventing custom resource to perform an upgrade. You do not need to specify the version for the `patch` number, because the Knative Operator matches the latest available `patch` number, as long as you specify `major.minor` for the version. For example, you only need to specify `"0.22"` to upgrade to the 0.22 release, you do not need to specify the exact `patch` number.
The Knative Operator supports up to the last three major releases. For example, if the current version of the Operator is 0.22, it bundles and supports the installation of Knative versions 0.19, 0.20, 0.21 and 0.22.
**NOTE:** In the following examples, Knative Serving custom resources are installed in the `knative-serving` namespace, and Knative Eventing custom resources are installed in the `knative-eventing` namespace.
## Performing the upgrade
To upgrade, apply the Operator custom resources, adding the `spec.version` for the Knative version that you want to upgrade to:
```yaml
kubectl apply -f - <<EOF
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
name: knative-serving
namespace: knative-serving
spec:
version: "0.22"
EOF
## Verifying the upgrade
To confirm that your Knative components have successfully upgraded, view the status of their pods in the relevant namespaces.
All pods will restart during the upgrade and their age will reset.
If you upgraded Knative Serving and Eventing, enter the following commands to get information about the pods for each namespace:
```bash
kubectl get pods --namespace knative-serving
```
```bash
kubectl get pods --namespace knative-eventing
```
These commands return something similar to:
```bash
NAME READY STATUS RESTARTS AGE
activator-6875896748-gdjgs 1/1 Running 0 58s
autoscaler-6bbc885cfd-vkrgg 1/1 Running 0 57s
autoscaler-hpa-5cdd7c6b69-hxzv4 1/1 Running 0 55s
controller-64dd4bd56-wzb2k 1/1 Running 0 57s
istio-webhook-75cc84fbd4-dkcgt 1/1 Running 0 50s
networking-istio-6dcbd4b5f4-mxm8q 1/1 Running 0 51s
storage-version-migration-serving-serving-0.20.0-82hjt 0/1 Completed 0 50s
webhook-75f5d4845d-zkrdt 1/1 Running 0 56s
```
```bash
NAME READY STATUS RESTARTS AGE
eventing-controller-6bc59c9fd7-6svbm 1/1 Running 0 38s
eventing-webhook-85cd479f87-4dwxh 1/1 Running 0 38s
imc-controller-97c4fd87c-t9mnm 1/1 Running 0 33s
imc-dispatcher-c6db95ffd-ln4mc 1/1 Running 0 33s
mt-broker-controller-5f87fbd5d9-m69cd 1/1 Running 0 32s
mt-broker-filter-5b9c64cbd5-d27p4 1/1 Running 0 32s
mt-broker-ingress-55c66fdfdf-gn56g 1/1 Running 0 32s
storage-version-migration-eventing-0.20.0-fvgqf 0/1 Completed 0 31s
sugar-controller-684d5cfdbb-67vsv 1/1 Running 0 31s
```
You can also verify the status of Knative by checking the custom resources:
```bash
kubectl get KnativeServing knative-serving --namespace knative-serving
```
```bash
kubectl get KnativeEventing knative-eventing --namespace knative-eventing
```
These commands return something similar to:
```bash
NAME VERSION READY REASON
knative-serving 0.20.0 True
```
```bash
NAME VERSION READY REASON
knative-eventing 0.20.0 True
```
## Rollback
If the upgrade fails, you can rollback to restore your Knative to the previous version. For example, if something goes wrong with an upgrade to 0.22, and your previous version is 0.21, you can apply the following custom resources to restore Knative Serving and Eventing to version 0.21.
For Knative Serving:
```yaml
kubectl apply -f - <<EOF
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
name: knative-serving
namespace: knative-serving
spec:
version: "0.21"
EOF
For Knative Eventing:
```yaml
kubectl apply -f - <<EOF
apiVersion: operator.knative.dev/v1alpha1
kind: KnativeEventing
metadata:
name: knative-eventing
namespace: knative-eventing
spec:
version: "0.21"
EOF

52
docs/install/upgrade-installation.md → docs/upgrade/upgrade-installation.md
View File

@ -1,17 +1,12 @@
---
title: "Upgrading your installation"
title: "Upgrading Knative"
weight: 21
type: "docs"
aliases:
- /docs/install/upgrade-installation
---
To upgrade your Knative components and plugins, run the `kubectl apply` command
to install the subsequent release. We support upgrading by a single
[minor](https://semver.org/) version number. For example, if you have v0.14.0 installed,
you must upgrade to v0.15.0 before attempting to upgrade to v0.16.0. To verify the version
number you currently have installed, see
[Checking your installation version](./check-install-version.md).
If you installed Knative using the [operator](https://github.com/knative/operator), the upgrade process will differ. See the [operator upgrade guide](./upgrade-installation-with-operator.md) to learn how to upgrade an installation managed by the operators.
You can use the `kubectl apply` command to upgrade your Knative components and plugins.
## Before you begin
@ -47,58 +42,39 @@ kubectl get pods --namespace knative-serving
kubectl get pods --namespace knative-eventing
```
### Upgrading plug-ins
### Upgrade plugins
If you have a plug-in installed, make sure to upgrade it at the same time as
If you have a plugin installed, make sure to upgrade it at the same time as
you upgrade your Knative components.
### Run pre-install tools before upgrade
In some upgrades there are some steps that must happen before the actual
upgrade, and these are identified in the release notes. For example, upgrading
from v0.15.0 to v0.16.0 for Eventing you have to run:
```bash
kubectl apply --filename {{< artifact repo="eventing" file="eventing-pre-install-jobs.yaml" >}}
```
upgrade, and these are identified in the release notes.
### Upgrade existing resources to the latest stored version
Our custom resources are stored within Kubernetes at a particular version.
As we introduce newer and remove older versions you'll need to migrate our resources
to the designated stored version. This ensures removing older versions
As we introduce newer and remove older supported versions, you must migrate the resources to the designated stored version. This ensures removing older versions
will succeed when upgrading.
For the various subprojects - we have a K8s job to help operators perform this migration.
The release notes for each release will explicitly whether a migration is required.
ie.
```bash
kubectl create --filename {{< artifact repo="serving" file="serving-post-install-jobs.yaml" >}}
```
For the various subprojects there is a K8s job to help operators perform this migration. The release notes for each release will state explicitly whether a migration is required.
## Performing the upgrade
To upgrade, apply the `.yaml` files for the subsequent minor versions of all
To upgrade, apply the YAML files for the subsequent minor versions of all
your installed Knative components and features, remembering to only
upgrade by one minor version at a time. For a cluster running v0.15.2 of the
Knative Serving and Eventing components, the
following command upgrades the installation to v0.16.0:
upgrade by one minor version at a time. For a cluster running version 0.20 of the Knative Serving and Eventing components, the following command upgrades the installation to v0.22.0:
```bash
kubectl apply --filename https://github.com/knative/serving/releases/download/v0.16.0/serving-core.yaml \
--filename https://github.com/knative/eventing/releases/download/v0.16.0/eventing.yaml \
kubectl apply -f https://github.com/knative/serving/releases/download/v0.22.0/serving-core.yaml \
-f https://github.com/knative/eventing/releases/download/v0.22.0/eventing.yaml \
```
### Run post-install tools after the upgrade
In some upgrades there are some steps that must happen after the actual
upgrade, and these are identified in the release notes. For example, after
upgrading from v0.15.0 to v0.16.0 for Eventing you should run:
```bash
kubectl apply --filename {{< artifact repo="eventing" file="eventing-post-install-jobs.yaml" >}}
```
upgrade, and these are identified in the release notes.
## Verifying the upgrade