[DX-1047] Upgrade Guides #4102
[DX-1047] Upgrade Guides #4102
Conversation
✅ PS. Pls add /docs/nightly to the end of url
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ PS. Pls add /docs/nightly to the end of url
To edit notification comments on pull requests, go to your Netlify site configuration. |
dcs3spp
changed the title
|
@allaneyles To facilitate reviewing the PR queue we are closing some PRs that are in draft status, e.g. awaiting docker images, videos, images etc. You can still update the PR and then open it again when ready for review. cc: @letzya |
There was a problem hiding this comment.
Hi @allaneyles @Fadzli-fast @Monica-Cedeno @nerdydread I have had a read through upgrade guides and content looks good! Review comments so far:
Self-Managed Custom Go Plugins
- Section headings do not match up with the version range in the table
- Are there some steps missing in bundling the plugins section:
- Upload the plugin bundle to a webserver
- Configure Gateway to download plugins from the webserver
- Add the plugin bundle filename (e.g. my-plugin-bundle.zip) as the ID in the Advanced options for an API in the Dashboard screen
- Should the bundling guide be included for each go plugin initialisation sections rather than just the section for versions > 5.1?
Pre-upgrade checks
- For this line Was Tyk deployed via a repository or .rpm (specifically for CentOS or RHEL)? Do you mean a package repository or an RPM file?
- For this line _Is the targeted version available on packagecloud.io or the intended version?_ Should this read "is the targeted version available on packagecloud.io or in local package repository?"
Upgrade Strategy
- For this paragraph A VM snapshot is a good way to replicate the environment but you may use other methods such as a new deployment process or the blue environment. If the latter is your choice, you may skip this manual and follow the deployment instructions on our documentation - https://tyk.io/docs
- Should blue environment be removed from this sentence since it is not a method to replicate the environment, e.g. the blue environment could itself be produced from a virtual machine snapshot.
- What is the deployment document that you wish to link to? Currently the PR links to https://tyk.io/docs?
Self-Managed RPM & DEB Guides
- What is the action of the target package version step in the guide?
- Images of building bundles, available versions of Tyk components are difficult to read.
Self Managed Hybrid
- Awaiting content to review
Cloud Saas
- Add supporting images to the guide
- Does the Go Plugins table match the section headings?
- Is there a guide that can link to for how to upgrade the Tyk Data Plane (Gateway)
I have refactored the structure in a separate PR, with a preview link available here for review. It creates separate pages for upgrade checklist, self-managed custom plugins and upgrade strategy to prevent duplicate content. If approved I can merge the suggested/reviewed structure into this PR.
dcs3spp
changed the title
* draft commit to refactor upgrading Tyk * update upgrading tyk structure * refactor upgrading tyk to link to new guides * add link to backup guide in prequisites * reorder important information steps --------- Co-authored-by: Simon Pears <[email protected]>
tyk-docs/content/upgrading-tyk.md
Outdated
| The sections below explain how to upgrade Tyk Gateway on: | ||
| - [Docker](#docker) | ||
| - [Kubernetes](#k8s) | ||
| - [Linux](#linux) |
There was a problem hiding this comment.
can we put the above in the same order of the content below?
| @@ -181,79 +186,6 @@ Instructions for upgrading Tyk gateway. You should follow the same flow for Tyk | |||
| <br> | |||
| Check the [helm upgrade docs](https://helm.sh/docs/helm/helm_upgrade/) for more details on the `upgrade` command. | |||
|
|
|||
|
|
|||
| ### Other installation choices | |||
There was a problem hiding this comment.
Where is this content? what is the purpose of this page? if it's an overview, shouldn't we have links to the content that was moved out of this page to another place?
Why did we leave k8s, help and docker but took out the rest?
| This page provides guidance for upgrading your Tyk installation. When upgrading Tyk, you need to consider each component (e.g. Gateway, Pump, Dashboard) separately, taking into account the deployment style you've implemented. We have structured this guide by deployment type (e.g. Cloud, Self-Managed, etc.) to keep all the information you need in one place. | ||
|
|
||
| ## Important to know | ||
| All our components adhere to a few common standards: |
There was a problem hiding this comment.
| All our components adhere to a few common standards: | |
| ## Upgrade standards and recommendations | |
| All our components adhere to a few common standards: |
|
|
||
| ## Next Steps {#next-steps} | ||
|
|
||
| Consult our [upgrade strategy]({{< ref "developer-support/upgrading-tyk/upgrade-strategy" >}}) guidelines to help you decide between a [Rolling]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#rolling-upgrade" >}}) or [Blue-Green]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#blue-green" >}}) upgrade. |
There was a problem hiding this comment.
| Consult our [upgrade strategy]({{< ref "developer-support/upgrading-tyk/upgrade-strategy" >}}) guidelines to help you decide between a [Rolling]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#rolling-upgrade" >}}) or [Blue-Green]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#blue-green" >}}) upgrade. | |
| Review our [upgrade strategy guidelines]({{< ref "developer-support/upgrading-tyk/upgrade-strategy" >}}) to decide between a [Rolling]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#rolling-upgrade" >}}) or [Blue-Green]({{< ref "developer-support/upgrading-tyk/upgrade-strategy#blue-green" >}}) upgrade. |
|
|
||
| | Platform | Guide | Description | | ||
| | ---------------- | ---------------- | ----------- | | ||
| | Tyk Cloud | [Cloud SaaS]({{< ref "developer-support/upgrading-tyk/cloud/cloud-saas" >}}) | Guide for Tyk Cloud SaaS (Software As A Service) | |
There was a problem hiding this comment.
@dcs3spp Not sure I don't get this. Why we have only linux here? where's docker and k8s?
| - Redis instance | ||
| - Tyk Pump (optional) | ||
|
|
||
| After reviewing your [upgrade pre-requisites]({{< ref "developer-support/upgrading-tyk/upgrade-prerequisites" >}}), |
There was a problem hiding this comment.
why pre-requisites and not prerequisites?
| @@ -0,0 +1,36 @@ | |||
| --- | |||
| title: "Upgrade Pre-Requisites" | |||
There was a problem hiding this comment.
it's is read more as "Pre Upgrade Considerations" than "Upgrade Pre-Requisites" to me, or maybe both? "Pre Upgrade Considerations and requirements". What do you think
|
|
||
| | Upgrade Path | Current Version | Target Version | | ||
| | ---- | --------------- | -------------- | | ||
| | [1](#path-1) | < 4.1.0 | < 4.1.0 | |
There was a problem hiding this comment.
| | [1](#path-1) | < 4.1.0 | < 4.1.0 | | |
| | [Path 1](#path-1) | < 4.1.0 | < 4.1.0 | |
| | Upgrade Path | Current Version | Target Version | | ||
| | ---- | --------------- | -------------- | | ||
| | [1](#path-1) | < 4.1.0 | < 4.1.0 | | ||
| | [2](#path-2) | < 4.1.0 | \>= 4.1.0 | |
There was a problem hiding this comment.
| | [2](#path-2) | < 4.1.0 | \>= 4.1.0 | | |
| | [Path 2](#path-2) | < 4.1.0 | \>= 4.1.0 | |
| | ---- | --------------- | -------------- | | ||
| | [1](#path-1) | < 4.1.0 | < 4.1.0 | | ||
| | [2](#path-2) | < 4.1.0 | \>= 4.1.0 | | ||
| | [3](#path-3) | \>= 4.1.0 | \>=5.1.0 | |
There was a problem hiding this comment.
| | [3](#path-3) | \>= 4.1.0 | \>=5.1.0 | | |
| | [Path 3](#path-3) | \>= 4.1.0 | \>=5.1.0 | |
| go mod vendor | ||
| ``` | ||
|
|
||
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. |
There was a problem hiding this comment.
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. | |
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler/tags) for available versions. |
| go mod vendor | ||
| ``` | ||
|
|
||
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. |
There was a problem hiding this comment.
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. | |
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. for v5.3 `docker pull tykio/tyk-plugin-compiler:v5.3`). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. |
| ``` | ||
|
|
||
| 3. Download the plugin compiler for the target version you’re upgrading to (e.g. 4.0.9). See the Tyk Docker Hub [repo](https://hub.docker.com/r/tykio/tyk-plugin-compiler) for available versions. | ||
| 4. [Compile]({{< ref "plugins/supported-languages/golang#building-the-plugin">}}) your plugin using this compiler |
There was a problem hiding this comment.
@dcs3spp can we give a better link? more direct to the compile command?
|
|
||
| ## Upgrade Guide Video | ||
|
|
||
| Please refer to our supporting [video](https://tyk-1.wistia.com/medias/t0oamm63ae) below for further guidance. |
There was a problem hiding this comment.
is it "further guidance" ?
|
|
||
| ## Upgrade Guide Video | ||
|
|
||
| Please refer to our supporting [video](https://tyk-1.wistia.com/medias/t0oamm63ae) below for further guidance. |
There was a problem hiding this comment.
| Please refer to our supporting [video](https://tyk-1.wistia.com/medias/t0oamm63ae) below for further guidance. | |
| Please refer to our [upgrade guide video](https://tyk-1.wistia.com/medias/t0oamm63ae) below for visual guidance: |
|
|
||
| 6. [Upload this bundle]({{< ref "tyk-cloud/configuration-options/using-plugins/uploading-bundle" >}}) to your configured S3 bucket. | ||
| 7. Update the [custom_middleware_bundle]({{< ref "plugins/how-to-serve-plugins/plugin-bundles#per-api--local-parameters" >}}) field in the API Definitions of all APIs that use your plugin. The field should be updated to use the new bundle file you created in step 5. | ||
| 8. Validate that your plugin is working per your expectations as at this stage, your Gateway will be running the plugin for your current version still. |
There was a problem hiding this comment.
| 8. Validate that your plugin is working per your expectations as at this stage, your Gateway will be running the plugin for your current version still. | |
| 8. Ensure that your plugin is functioning as expected, as at this stage, your Gateway will still be running the plugin for the current version. |
| - MongoDB | ||
| - Redis (Master Instance) | ||
| - Management Gateway | ||
| - MDCB |
There was a problem hiding this comment.
Why don't we call it "control plane"?
| ## 1. Upgrade your Control Plane | ||
| See Tyk Guide for how to [Upgrade Control Planes]({{< ref "tyk-cloud/environments-&-deployments/managing-control-planes#upgrade-control-planes" >}}) | ||
|
|
||
| ## 2. Upgrade your Go Plugins |
There was a problem hiding this comment.
@dcs3spp we need to underatand from Travis why this info is repeated in saas and hybrid. Do we have to have duplicated content? I'd rather having a page "upgrade Tyk compiler".
For example, step 8 that I improved in the other page, now needs to be improved here. Duplicated content is a very bad idea
|
|
||
| ## 3. Upgrade your Data Plane Hybrid Gateway(s){#upgrading-data-plane-hybrid-gateways} | ||
| Follow the instructions for component deployment type: | ||
| - **Docker** |
There was a problem hiding this comment.
now we have this section and also this page https://deploy-preview-4102--tyk-docs.netlify.app/docs/nightly/developer-support/upgrading-tyk/other-upgrade-options/docker/ - they essentially do the same thing. Can you please improve this to avoid dup of content? same for helm.
Same for Linux distro. We have content her but also a separate page for it https://deploy-preview-4102--tyk-docs.netlify.app/docs/nightly/developer-support/upgrading-tyk/self-managed/linux-distributions/self-managed-rpm/
|
|
||
| In a production environment, where we recommend installing the Dashboard, Gateway, and Pump on separate machines, you should upgrade components in the following sequence: | ||
|
|
||
| 1. Tyk Gateway |
There was a problem hiding this comment.
@dcs3spp The order here is not consistent with the order we currently have in our docs.
There was a problem hiding this comment.
@dcs3spp Added a few comments. Also the order of the upgrade in self managed is not consistent.
Could you kindly check why and re-review the whole content in holistic way to make sure the rest is consistent, the guide is flowing and the navigation makes sense (currently it needs work)
For internal users - Please add a Jira DX PR ticket to the subject!
DX-1047
Preview Link
Draft Overview
Upgrade PreRequisites
Upgrade Strategy
Self Managed Go Plugins
Self Managed Debian
Self Managed RPM
Hybrid
Cloud Saas
Description
This PR adds the template structure for adding the Go plugins upgrade documents. For quicker review and release a separate PR will be created for the other deployment upgrade guides
Screenshots (if appropriate)
Checklist
master.