-
Notifications
You must be signed in to change notification settings - Fork 589
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.
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
Adding migration guide for on-prem to konnect #7482
Conversation
✅ Deploy Preview for kongdocs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
026ea45
to
f2ecea7
Compare
7340e88
to
53b9549
Compare
53b9549
to
64ca3c2
Compare
Mid-reviewing right now, but one thought: should we combine your guide with this topic? https://deploy-preview-7482--kongdocs.netlify.app/konnect/getting-started/import/ - or does it still serve a standalone purpose in a "Getting started" context 🤔 ? I also don't think this page quite belongs in the "Introduction", but there's no existing section for it either. It might be better to have it stand alone, as a top-level item. |
Thanks @lena-larionova. I agree these pages overlap. I would vote to have the new page supersede the current "Import" page. I don't think the current page covers anything that the new page does not except for the CTAs at the bottom. I could copy those over if you agree. We could also move the new page into the Getting Started section where the current page is if that makes more sense. |
64ca3c2
to
1c7c788
Compare
@lena-larionova I refactored this based on my previous comment and rebased of main. Let me know what you think. Thanks for the review. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel like this doc is trying to solve two things at once. It feels like it is trying to teach me the concepts of migration and showing me how to do some pieces of the migration process. The headings bury a lot of key information under the large umbrella of Migration Guide.
What if you structured the information sort of like this:
## The migration process
A high level overview of the steps, maybe a chart that shows what order we recommend migrating things in.
### Pre-migration
Things like making sure you have the right roles and permissions configured.
A Konnect Account with the right permissions
Maybe even the section on stripping metadata from your workspaces.
IAM section?
## Migrating the Kong Gateway Configuration
The general process for migrating the configuration involves “dumping” your existing on-premises configuration to a local file, modifying the configuration slightly to remove any workspace specific metadata, and then synchronizing the configuration to your desired Control Plane in Kong Konnect.
### Export from Kong Gateway
- Using decK to Export Configuration
### Modify the configuration
- Metadata
- other things that you might want to modify here
### Import to Konnect
## Plugins
## Additional migration information
## Other Konnect use cases
Hopefully that makes sense, In essence, I think having a lot of information for a topic like this can be very good, but I think the steps that lead a user to the outcome of migration should be prioritized.
```sh | ||
yq -i 'del(._workspace)' default.yaml | ||
yq -i 'del(._workspace)' inventory.yaml | ||
yq -i 'del(._workspace)' sales.yaml | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we use something built-in like sed or awk?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO this isn't necessary. yq
and jq
are standard in developer workflows that manipulate files of these formats. Given this is a "hint" to how to perform the migration and not a recipe for any automated workflow, I don't think the use of the tool is concerning.
@@ -0,0 +1,318 @@ | |||
--- | |||
title: Migrating from Kong Gateway On-Premises to Kong Konnect |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From the title I'm expecting a step-by-step guide on how to migrate. The steps written feel more abstract, and I understand that everyones case is different but if we want to use illustrative steps maybe we can reorder them so that they express a recommended order of operations?
Like:
- Export config
- Modify Config
- Import config
- Setup RBAC
- Migrate Data planes
Then you have extra information that may not apply to everyone like:
Handling plugins
Co-authored-by: Angel <Guaris@users.noreply.github.com>
Migration guide for on-prem Kong Gateway to Konnect.
https://deploy-preview-7482--kongdocs.netlify.app/konnect/getting-started/migration/