Add user facing doc for management-components upgrade #7661
Conversation
eks-distro-bot
added
the
size/M
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #7661 +/- ##
==========================================
+ Coverage 73.48% 73.60% +0.12%
==========================================
Files 579 588 +9
Lines 36357 37150 +793
==========================================
+ Hits 26718 27346 +628
- Misses 7875 8013 +138
- Partials 1764 1791 +27 ☔ View full report in Codecov by Sentry. |
d8660091
force-pushed
the
upgrade-management-components-doc
branch
3 times, most recently
from
6ce7e98 to
db70e2a
Compare
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
docs/content/en/docs/clustermgmt/cluster-upgrades/management-components-upgrade.md
Outdated
Show resolved
Hide resolved
d8660091
force-pushed
the
upgrade-management-components-doc
branch
from
db70e2a to
0938f47
Compare
| How to perform management components upgrade for management clusters | ||
| --- | ||
|
|
||
| >**_NOTE:_** The `upgrade management-components` sub-command is added in `eksctl anywhere` version `v0.19.0` for all providers. Management components upgrades can only be done through the `eksctl anywhere` cli, not through the Kubernetes API. |
There was a problem hiding this comment.
is added in EKS Anywhere version v0.19.0 for all providers
|
|
||
| ### What are “management components”? | ||
|
|
||
| Management components are the Kubernetes resources in an EKS Anywhere management cluster that are responsible for managing the EKS Anywhere clusters' lifecycle. Key components include, but are not limited to: |
There was a problem hiding this comment.
Management components run on management or standalone clusters and are responsible for managing the lifecycle of workload clusters. Management components include but are not limited to:
- Cluster API controller
- EKS Anywhere cluster lifecycle controller
- Curated Packages controller
- Provider-specific controllers (vSphere, Tinkerbell etc.)
- Tinkerbell services (Boots, Hegel, Rufio, etc.)
- Custom Resource Definitions (CRDs) (
clusters,eksareleases, etc.)
|
|
||
| ### Why upgrade management components separately? | ||
|
|
||
| The `upgrade cluster` command, when executed against a management cluster, not only upgrades its management components but also initiates a comprehensive upgrade of the management cluster itself. This process often entails node replacement and significant operational tasks, which might be deemed risky for some production environments due to the potential of replacing all Kubernetes nodes. |
There was a problem hiding this comment.
The existing eksctl anywhere upgrade cluster command, when run against management or standalone clusters, upgrades both the management and workload components. When upgrading versions, this upgrade process performs a rolling replacement of nodes in the cluster, which brings operational complexity, and should be carefully planned and executed.
|
|
||
| The `upgrade cluster` command, when executed against a management cluster, not only upgrades its management components but also initiates a comprehensive upgrade of the management cluster itself. This process often entails node replacement and significant operational tasks, which might be deemed risky for some production environments due to the potential of replacing all Kubernetes nodes. | ||
|
|
||
| However, to leverage enhancements to newer EKS Anywhere version, such as bug fixes in the new management components without the extensive risk, it's advisable to initially upgrade only the management components. This step ensures minimal disruption and risk. Subsequently, you can proceed to upgrade the workload cluster at a more convenient time, once you're confident in the stability and readiness of your environment. This strategy provides a more controlled and efficient method to update your cluster's management infrastructure, aligning upgrades with your readiness and risk tolerance levels. |
There was a problem hiding this comment.
With the new eksctl anywhere upgrade management-components command, you can upgrade management components separately from workload components. This is enables you to get the latest updates to the management components such as Cluster API controller, EKS Anywhere controller, and provider-specific controllers without a rolling replacement of nodes in the cluster, which reduces the operational complexity of the operation.
|
|
||
| ### Check management components versions | ||
|
|
||
| You can check the current and new versions of management components with the `upgrade plan management-components` command: |
There was a problem hiding this comment.
eksctl anywhere upgrade plan management-components
| etcdadm-controller v1.0.16+0ed68e6 v1.0.17+5e33062 | ||
| ``` | ||
|
|
||
| Alternatively, you can run `upgrade plan cluster` command against your management cluster, which should give you the version differences for both management and non-management components. |
There was a problem hiding this comment.
Alternatively, you can run the eksctl anywhere upgrade plan cluster command against your management cluster, which shows the version differences for both management and workload components.
|
|
||
| Alternatively, you can run `upgrade plan cluster` command against your management cluster, which should give you the version differences for both management and non-management components. | ||
|
|
||
| ### Perform management components upgrade |
There was a problem hiding this comment.
Upgrade Management Components
|
|
||
| ### Perform management components upgrade | ||
|
|
||
| To perform the upgrade, run the following command: |
There was a problem hiding this comment.
To perform the management component upgrade, run the following command:
| 🎉 Management components upgraded! | ||
| ``` | ||
|
|
||
| At this point, a new `eksaVersion` will be available in your management cluster. If you want to upgrade your workload cluster, you can still run "eksctl anywhere upgrade cluster" or simply edit your workload cluster's `eksaVersion` field and apply it. |
There was a problem hiding this comment.
At this point, a new
eksaVersionwill be available in your management cluster.
What does this mean?
If you want to upgrade your workload cluster, you can still run "eksctl anywhere upgrade cluster" or simply edit your workload cluster's
eksaVersionfield and apply it.
After your management components are upgraded, you can subsequently run a workload cluster upgrade with the eksctl anywhere upgrade cluster command, or by changing your workload cluster's spec and applying it to your management cluster with Kubernetes API-compatible tooling such as kubectl, GitOps, or Terraform.
d8660091
force-pushed
the
upgrade-management-components-doc
branch
from
0938f47 to
3c5fb9b
Compare
| /docs/tasks/cluster/cluster-upgrades/management-components-upgrade/ | ||
| date: 2024-02-21 | ||
| description: > | ||
| How to perform management components upgrade for management clusters |
There was a problem hiding this comment.
How to upgrade EKS Anywhere management components
| How to perform management components upgrade for management clusters | ||
| --- | ||
|
|
||
| >**_NOTE:_** The `upgrade management-components` sub-command is added in `EKS Anywhere` version `v0.19.0` for all providers. Management components upgrades can only be done through the `eksctl anywhere` cli, not through the Kubernetes API. |
There was a problem hiding this comment.
The eksctl anywhere upgrade management-components subcommand was added in EKS Anywhere version v0.19.0 for all providers. Management component upgrades can only be done through the eksctl CLI, not through the Kubernetes API.
| 🎉 Management components upgraded! | ||
| ``` | ||
|
|
||
| At this point, a new `eksaVersion` custom resource will be available in your management cluster. You can subsequently run a workload cluster upgrade with the `eksctl anywhere upgrade cluster command`, or by updating `eksaVersion` field in your workload cluster's spec and applying it to your management cluster with Kubernetes API-compatible tooling such as kubectl, GitOps, or Terraform. |
There was a problem hiding this comment.
At this point, a new eksaVersion custom resource will be available in your management cluster, which means new cluster components that correspond to the eksaVersion are available for cluster upgrades.
d8660091
force-pushed
the
upgrade-management-components-doc
branch
from
3c5fb9b to
5cf4aeb
Compare
|
[APPROVALNOTIFIER] This PR is APPROVED Approval requirements bypassed by manually added approval. This pull-request has been approved by: The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
/cherrypick release-0.19 |
|
@d8660091: new pull request created: #7703 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
Issue #, if available:
Description of changes:
Testing (if applicable):
Documentation added/planned (if applicable):
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.