[DX-1047] Upgrade Guides

[dcs3spp]

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

• [x] I have added a preview link to the PR description.
• [x] I have reviewed the guidelines for contributing to this repository.
• [x] I have read the technical guidelines for contributing to this repository.
• [x] Make sure you have started your change off our latest master.
• [x] I labelled the PR

[netlify[bot]]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	5cd0f8c2b736582a9a786bde405d220b74714b9b
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/65c3c19db81d9a000793bfec
😎 Deploy Preview	https://deploy-preview-4102--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify[bot]]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	8fbcd14715454969adf14ebc9c37ce14aeb81fec
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/667170e09126ce0008cee23a
😎 Deploy Preview	https://deploy-preview-4102--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[dcs3spp]

@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

[Fadzli-fast]

Hey @dcs3spp, allow to explain some parts from the guide

Self-Managed RPM & DEB Guides What is the action of the target package version step in the guide?

• This section is for users to identify the version that they are upgrading into after their initial discussion on which versions to upgrade to. Eg, the customer has decided to upgrade to version 5.2.5, isit available for their specific OS Rhel(el/7, el/8) or Ubuntu focal, bionic etc.

Images of building bundles, available versions of Tyk components are difficult to read

• Will it be better removed? as its quite straight forward? This images are usually requested by APAC customers. eg Do you have an example of how it looks like?

Upgrade Strategy What is the deployment document that you wish to link to?

• I believe its supposed to point to the deployment page

Self-Managed Custom Go Plugins Should the bundling guide be included for each go plugin initialisation sections rather than just the section for versions > 5.1?

This is on assumption IF you are using bundles to ship your plugins, to avoid confusion I feel its better if the bundling section is added into the guide rather then creating a bunch of different instructions? eg If you are using bundles to ship your plugins refer to link

[nerdydread]

@dcs3spp Thank you for the feedback, changes have been applied in the following commit.

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)

• Added images for showing an example of a bundle’s contents.
• The table and section headings have been updated to match.
• Removed the steps and linked to the existing guide for upgrading the Tyk Data Plane. Added links to other existing docs for certain steps as some things were already well documented and this would cut down on the amount of duplication.

[dcs3spp]

@allaneyles @Fadzli-fast @Monica-Cedeno @nerdydread I have reviewed the Hybrid upgrade guide and also updated the Hybrid and Cloud SaaS guides for formatting, added links and sub-section headings. In the Hybrid Gateway document I have also updated the definition of hybrid Gateway so that it relates to MongoDB or PostgreSQL.

The following is a summary of the DX review and a peer review should also be requested before this is released.

Self-Managed Custom Go Plugins

• Section headings do not match up with the version range in the table

Self Managed RPM

• A new image is required for available versions of Tyk components. Existing image is difficult to read.

Hybrid - Moved into cloud sub-menu ✅

• Is definition of hybrid correct? Is hybrid also where client hosts a Gateway in 3rd party cloud provider or on their own server?
• Should the plugins be updated on the Management Gateway also?
• Go plugins section has image of plugin bundle files with year of 1979
• Go plugins section step 5 image needed for path 1 & path 3 to match version of upgrade represented by section heading
• Path 1 & Path 3 manifest.json file example does not contain both plugin .so files but path 2 does, why? Should this be updated for paths 1 & 3 to include both plugin .so files?
• Path 3 of Go Plugins: Are steps 7 & 10 duplicated?
• Go Plugins: Steps 7, 8, 9 & 10 are in different order across upgrade paths. Update with correct consistent recommended ordering.
• In Go plugins path 1 - 3 should the link for upgrading Hybrid Gateway(s) refer to this section? I have added this as part of refactoring.
• Update Go plugin path section headings to match table, similar to Cloud SaaS.

Cloud Saas ✅

• Go plugins section has image of plugin bundle files with year of 1979
• Go plugins section step 5 image needed for path 1 & path 3 to match version of upgrade represented by section heading
• Path 1 & Path 3 manifest.json file example does not contain both plugin .so files. Should this be updated for paths 1 & 3 to include both plugin .so files?
• Steps 7, 8 & 9 are in different order of Go plugins for Paths 1 - 3 Should they be the same order?
• In go plugins paths 1-3 add a link for the step that involves upgrading to the Cloud Data Plane. Should it link to this section? I have added the link and double checking for code review
• Path 3 (Upgrade From Current Version >= 4.1.0 To Target Version >= 5.1.0) gives an example for upgrading to Target Version > v4.20 and < v5.1.0. Should this example be removed since it does not match the scenario represented by the path 3 section heading?

Are the Go plugins steps the same for Hybrid and Cloud Saas, or is it safer to have them as separate?

[Fadzli-fast]

Hey @dcs3spp,

I have updated the ones below

[Self-Managed Custom Go Plugins](http://localhost:1313/docs/nightly/developer-support/upgrading-tyk/self-managed/go-plugins/)

Section headings do not match up with the version range in the table

Already changed it to be consistent with the other guides to avoid confusion.

[Self Managed RPM](https://deploy-preview-4102--tyk-docs.netlify.app/docs/nightly/developer-support/upgrading-tyk/self-managed/linux-distributions/self-managed-rpm/)

A new image is required for available versions of Tyk components. Existing [image](https://deploy-preview-4102--tyk-docs.netlify.app/docs/nightly/developer-support/upgrading-tyk/go-plugins/self-managed-rpm/#check-upgradable-packages) is difficult to read.

I have changed the screenshots to be more easier to read focusing on the example printout of the command.

Also made some change under databases with a note stating that we dont own them and this a guide only.

Also removed screenshots for mongo restore as it wasnt helpful plus its hard to see.

[dcs3spp]

Thanks @Fadzli-fast Images look much better in the linux Debian & Redhat section. I like the idea of adding the note in databases backup!!!

[dcs3spp]

@allaneyles @Fadzli-fast @Monica-Cedeno @nerdydread Feedback remaining is Hybrid & Cloud Saas

[nerdydread]

Hey @dcs3spp I've made the following updates based on your feedback:

Hybrid - Moved into cloud sub-menu

• Is definition of hybrid correct? Is hybrid also where client hosts a Gateway in 3rd party cloud provider or on their own server? I was copying/pasting between the SaaS and Hybrid document as they’re similar and missed some of the updates in my first pass. This has been updated accordingly. ✅
• Should the plugins be updated on the Management Gateway also? No, the plugins aren’t needed on the Management Gateway as this Gateway doesn’t proxy any API traffic. ✅
• Go plugins section has image of plugin bundle files with year of 1979 This is a result of the zip utility I used, it stripped the data modified value. I’ve gone back and modified the Date Modified for each of the images so as to not be a source of confusion. ✅
• Go plugins section step 5 image needed for path 1 & path 3 to match version of upgrade represented by section heading Updated this accordingly. ✅
• Path 1 & Path 3 manifest.json file example does not contain both plugin .so files but path 2 does, why? Should this be updated for paths 1 & 3 to include both plugin .so files? We introduced our Go Plugin Loader functionality in 4.1.0 that allowed users to include multiple versions of a given plugin in the same bundle and the Gateway would then select the appropriate version to load. This allows for users to include their target version and current version plugin in the same bundle package prior to upgrading so that post-upgrade, the Gateway can pull the appropriate version automatically. For Path 1 (< 4.1.0), you have to upgrade the Gateway then load the target version plugin. For Paths 2 and 3, the target version plugin can be bundled and pulled down by the Gateway prior to upgrading. Path 3 has been updated to include both .so files. ✅
• Path 3 of Go Plugins: Are steps 7 & 10 duplicated? This has been updated to be more clear. ✅
• Go Plugins: Steps 7, 8, 9 & 10 are in different order across upgrade paths. Update with correct consistent recommended ordering. Updated accordingly, the Go Plugin Loader functionality introduced in v4.1.0 is why the steps are different between Path 1 and Paths 2-3. ✅
• In Go plugins path 1 - 3 should the link for upgrading Hybrid Gateway(s) refer to this section? I have added this as part of refactoring. Yes this should link to the existing documentation on upgrading Cloud Control Planes. This has been updated. ✅
• Update Go plugin path section headings to match table, similar to Cloud SaaS. ✅ This has been updated.

Cloud Saas

• Go plugins section has image of plugin bundle files with year of 1979 This has been updated as the zip utility I used at the time stripped the Date Modified attribute. ✅
• Go plugins section step 5 image needed for path 1 & path 3 to match version of upgrade represented by section heading ✅ This has been updated accordingly for each path.
• Path 1 & Path 3 manifest.json file example does not contain both plugin .so files. Should this be updated for paths 1 & 3 to include both plugin .so files? Same answer as the Hybrid section above. ✅
• Steps 7, 8 & 9 are in different order of Go plugins for Paths 1 - 3 Should they be the same order? Updated accordingly, the Go Plugin Loader functionality introduced in v4.1.0 is why the steps are different between Path 1 and Paths 2/3. ✅
• In go plugins paths 1-3 add a link for the step that involves upgrading to the Cloud Data Plane. Should it link to this section? I have added the link and double checking for code review Yes this should link to the existing documentation on upgrading Cloud Control Planes. This has been updated.✅
• Path 3 (Upgrade From Current Version >= 4.1.0 To Target Version >= 5.1.0) gives an example for upgrading to Target Version > v4.20 and < v5.1.0. Should this example be removed since it does not match the scenario represented by the path 3 section heading? This has been removed. ✅
• Are the Go plugins steps the same for Hybrid and Cloud Saas, or is it safer to have them as separate? They’re nearly identical, the only difference really is that SaaS deployments will use an S3 Bucket for plugin bundles while Hybrid deployments will use a file server. ✅

[letzya]

about cloud saas >=5.1.0 - we should check if this works with 5.3 and get confirmation for it @andyo-tyk

[Monica-Cedeno]

this looks great. Thanks @letzya and @dcs3spp

[github-actions[bot]]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review [1-5]	3
🧪 Relevant tests	No
🔒 Security concerns	No
⚡ Key issues to review	Possible Bug: The use of go get in the upgrade paths may not specify the exact version of the dependencies, which could lead to non-reproducible builds or unexpected updates.
	Documentation Clarity: The upgrade paths could benefit from more detailed explanations or step-by-step instructions to ensure clarity, especially for users unfamiliar with Go modules or Docker operations.

[github-actions[bot]]

PR Code Suggestions ✨

Category	Suggestion	Score
Possible bug	Correct the incomplete go get command to prevent execution errors The command go get in the code block is incomplete and might cause confusion or errors when users try to follow the guide. It should either be removed if unnecessary or completed with a proper package path. tyk-docs/content/developer-support/upgrading-tyk/go-plugins.md [25] -go get +# go get <package-name> Suggestion importance[1-10]: 9 Why: Correcting the incomplete go get command is important to prevent execution errors and confusion for users following the guide.	9
Consistency	Add missing 'path' key to maintain consistency Consider adding a 'path' key for the "Tyk Upgrade Guides" directory to maintain consistency with other directory entries which have a path defined. tyk-docs/data/menu.yaml [4211-4213] - title: "Tyk Upgrade Guides" + path: /developer-support/upgrading-tyk category: Directory show: True Suggestion importance[1-10]: 9 Why: Adding the 'path' key for the "Tyk Upgrade Guides" directory ensures consistency with other directory entries, improving maintainability and clarity.	9
Possible issue	Correct the date format in the document's front matter The date format in the front matter should be corrected to ensure consistency and proper parsing by static site generators or other tools. The current date format '2024-03-1' might be misinterpreted or cause errors due to the missing leading zero in the day part. tyk-docs/content/developer-support/upgrading-tyk/go-plugins.md [3] -date: 2024-03-1 +date: 2024-03-01 Suggestion importance[1-10]: 8 Why: Correcting the date format is crucial for consistency and proper parsing by tools, which can prevent potential errors.	8
	Correct a typo to enhance the document's professionalism It's recommended to correct the typo in "varios" to "various" in line 10 to maintain the professionalism and accuracy of the documentation. tyk-docs/content/upgrading-tyk.md [10] -(Docker, Helm, K8S, varios Linux distributions). +(Docker, Helm, K8S, various Linux distributions). Suggestion importance[1-10]: 8 Why: Correcting typos is crucial for maintaining professionalism and accuracy in documentation, which is important for user trust and comprehension.	8
Best practice	Replace backticks with quotes in the docker command to enhance compatibility The use of backticks for paths in the docker run command might cause issues on certain platforms or shells. It's safer to use quotes to ensure compatibility across different environments. tyk-docs/content/developer-support/upgrading-tyk/go-plugins.md [92] -docker run --rm -v `pwd`:/plugin-source \ +docker run --rm -v "$(pwd)":/plugin-source \ Suggestion importance[1-10]: 8 Why: Replacing backticks with quotes in the docker command enhances compatibility across different environments, which is a best practice.	8
	Standardize the capitalization of boolean values Ensure consistent capitalization in boolean values for the 'show' key. Some entries use 'True' while others use 'true'. YAML is case-sensitive, and it's best practice to maintain consistency. tyk-docs/data/menu.yaml [4207-4221] -show: True +show: true show: true Suggestion importance[1-10]: 8 Why: Consistent capitalization in boolean values improves readability and avoids potential issues with parsers that may be case-sensitive.	8
	Ensure consistent boolean value usage for 'show' key Ensure that the 'show' key for all entries is consistently set to 'true' or 'false' to avoid potential issues with case sensitivity in different parsers or platforms. tyk-docs/data/menu.yaml [4207-4221] -show: True +show: true show: true Suggestion importance[1-10]: 8 Why: Ensuring consistent boolean value usage for the 'show' key avoids potential issues with case sensitivity and improves code readability.	8
Enhancement	Add a newline after the front matter for better readability It's recommended to add a newline after the front matter block to separate it visually and syntactically from the content that follows. This enhances readability and helps in maintaining a clean structure in markdown files. tyk-docs/content/developer-support/upgrading-tyk/go-plugins.md [8] +--- - Suggestion importance[1-10]: 7 Why: Adding a newline after the front matter improves readability and maintains a clean structure, which is beneficial for document maintenance.	7
	Improve clarity and readability by breaking complex information into bullet points To enhance clarity and readability, consider breaking the long sentence in line 10 into multiple sentences or using bullet points to list the components and deployment styles. tyk-docs/content/upgrading-tyk.md [8-10] -When upgrading Tyk, you need to consider the model you are on (SaaS, Self Managed, Hybrid or OSS). Then depending on that understand which components you should upgrade (e.g. Gateway, Pump, Dashboard, Go Plugins), while taking into account the deployment style you've implemented (Docker, Helm, K8S, varios Linux distributions). +When upgrading Tyk, consider the following: +- **Model**: SaaS, Self Managed, Hybrid, or OSS. +- **Components**: Depending on your model, upgrade relevant components such as Gateway, Pump, Dashboard, or Go Plugins. +- **Deployment Style**: Take into account the deployment style you've implemented, such as Docker, Helm, K8S, or various Linux distributions. Suggestion importance[1-10]: 7 Why: Breaking the information into bullet points significantly improves readability and clarity, making it easier for users to understand the upgrade process.	7
	Remove redundant phrases to enhance clarity To avoid redundancy and enhance clarity, consider removing the repeated phrase "before starting the upgrade" in line 27, as it is already clear from the context. tyk-docs/content/upgrading-tyk.md [27] -Before starting the upgrade make sure you have consulted the [preparation guidelines]({{< ref "developer-support/upgrading-tyk/preparations/upgrade-guidelines" >}}) before starting the upgrade. +Make sure you have consulted the [preparation guidelines]({{< ref "developer-support/upgrading-tyk/preparations/upgrade-guidelines" >}}) before starting the upgrade. Suggestion importance[1-10]: 6 Why: Removing redundant phrases enhances clarity and readability, though it is a minor improvement.	6
	Improve the consistency and professionalism of section headers through capitalization Consider using consistent capitalization for section headers to improve readability and maintain a professional tone throughout the document. For example, "Standards and recommendations" should be capitalized as "Standards and Recommendations". tyk-docs/content/upgrading-tyk.md [15] -## Standards and recommendations +## Standards and Recommendations Suggestion importance[1-10]: 5 Why: The suggestion improves consistency and professionalism but is a minor enhancement and does not address any critical issues.	5
Maintainability	Remove redundant category specification Remove the redundant 'category: Directory' from the "Tyk Cloud upgrade guide" as it is already nested under a directory and does not need to be specified again. tyk-docs/data/menu.yaml [4236-4237] - title: "Tyk Cloud upgrade guide" - category: Directory show: True Suggestion importance[1-10]: 7 Why: Removing redundant specifications helps to keep the code clean and maintainable, although it is a minor improvement.	7

[letzya]

/release to release-5.3

[tykbot[bot]]

Working on it! Note that it can take a few minutes.

[tykbot[bot]]

@letzya Succesfully merged PR