[Rancher2] Documentation for RKE2 provisioning

sowmyav27 commented 2 years ago

Documentation for RKE2 provisioning is incomplete / needs to be reviewed for RKE2 being GA in 2.6.5.

General Documentation

[x] "Launching Kubernetes with Rancher" section
- Associated PR https://github.com/rancher/docs/pull/4075
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters
- Section for the most part is written for RKE1 with RKE2 being limited to the "Changes in Rancher v2.6" section (https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/#changes-in-rancher-v2-6).
  - [x] @btat & @jtravee, what are your thoughts on making RKE1 vs. RKE2 more prominent in this section? For example, section on Terraform there needs to link different resource for RKE2 (https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2)
[x] "Launching Kubernetes on New Nodes in an Infrastructure Provider" section
- Associated PR https://github.com/rancher/docs/pull/4075
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/
- Mostly the same as above, this section is mostly RKE1-specific with some RKE2 notes scattered around it.
  - [x] @btat & @jtravee, same as above: what are your thoughts on making RKE1 vs. RKE2 more prominent in this section?
[ ] Specific infrastructure providers
- [x] Amazon EC2 (the same approach as Azure, see details there)
  - Current PR for reference: https://github.com/rancher/docs/pull/4084
- [x] DigitalOcean (the same approach as Azure, see details there)
  - Current PR for reference: https://github.com/rancher/docs/pull/4085
- [x] Azure
  - Current docs links:
    - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/
  - Current PR for reference: https://github.com/rancher/docs/pull/4066
  - For RKE1 node template configuration is not too verbose. Is it due to RKE1 showing limited options or more due to the documentation approach not being to document all options? For RKE2 per the linked PR the approach seems to be a bit more in-depth: https://github.com/rancher/docs/pull/4066/files#diff-ea7f24f91b5e6cb6d4fca419a9bb769b1ddc9fa124bb0b9751c49d44022312a1. @btat
- [x] ~~Nutanix~~ (no custom RKE2 UI, handled the same way as any other node driver - autogenerated UI based on available fields)
- [ ] vSphere (the same approach as Azure, see details there)
  - Current PR for reference: https://github.com/rancher/docs/pull/4083
[x] RKE2 Configuration Reference
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/
- [x] "(Tech Preview)" note needs to be removed (stating it requires 2.6.5)
  - Associated PR: https://github.com/rancher/docs/pull/4067
- [x] Cluster Config File (explaining "Edit as YAML") section probably needs to be expanded as it's rather vague
  - Associated PR: https://github.com/rancher/docs/pull/4086
- Contents to be reviewed for correctness/completeness in general
[ ] Behavior Differences Between RKE1 and RKE2
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/behavior-differences-between-rke1-and-rke2/
- [ ] @thedadams & @Oats87, please review it and determine if the information there is still applicable for 2.6.5 and if there are any corrections/additions needed

Added as of 5/9/22

[ ] Upgrading and Rolling Back Kubernetes
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/upgrading-kubernetes/#enabling-draining-nodes-during-upgrades-from-the-rancher-ui
- Link above is RKE1-specific, with some section generally applicable to RKE2. Suggested creating a separate page for RKE2 clusters.
[ ] Nodes and Node Pools
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/nodes/
- Link above covers different types of clusters, with the assumption that custom and node-provisioned clusters are RKE1. Probably need to add RKE2 specifics.
[x] Cluster Templates
- ~~Current docs links:~~
  - ~~https://rancher.com/docs/rancher/v2.6/en/admin-settings/rke-templates/~~
- ~~Very much RKE1-specific, many child pages too.~~
- ~~This needs to be created for RKE2 from scratch.~~
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/admin-settings/cluster-templates/
- The "Cluster Templates" page covers RKE2 Cluster Templates well enough, though not to the same level of detail as RKE Templates section referenced above (strikethrough).
  - @btat @jtravee , please log enhancement to add more details to RKE2 Cluster Templates section to be at the similar level of details as RKE Templates. This is not critical for 2.6.5 release though.
    - Billy: https://github.com/rancher/rancher-docs/issues/52 created. Marking this task done in the context of the 2.6.5 release.

Major Features

[x] etcd snapshot support (with options) - https://github.com/rancher/rancher/issues/34417
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/backing-up-etcd/
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/restoring-etcd/
- Links above are RKE1-specific.
  - [x] @btat & @jtravee, looking for guidance on how to best incorporate RKE2-specific information there. There is a fair amount of difference as far as I know, so maybe it's best to have separate pages for RKE2-provisioned clusters snapshot/restore.
- Engineering expert: @Oats87
  - [x] @Oats87, please review the current documentation linked above and determine how much is the same/different vs. what it should be for RKE2.
- Associated PR https://github.com/rancher/rancher-docs/pull/502
[x] On-demand certificate rotation - https://github.com/rancher/rancher/issues/35343
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/certificate-rotation/
- Link above is RKE1-specific, but at a glance seems to be fully applicable to RKE2.
- Associated PR: https://github.com/rancher/docs/pull/4087
- Engineering expert: @paynejacob
  - [x] @paynejacob, please review and confirm no RKE2-specific updates are needed
[x] Rancher-managed encryption keys (with rotation) - https://github.com/rancher/rancher/issues/35436
- Current docs links:
  - No Rancher documentation found; RKE1 documentation exists (https://rancher.com/docs/rke/latest/en/config-options/secrets-encryption/), but doesn't cover Rancher functionality around this.
    - [x] @btat & @jtravee, please help with locating Rancher-specific documentation for this feature
      - Does not exist, will need to be created.
- Overall, need to add a note that as of 2.6.5 encryption keys rotation is not supported (however note encryption key rotation is always enabled in RKE2 - https://github.com/rancher/rke2/issues/850)
- Associated PR: https://github.com/rancher/docs/pull/4230
[x] SSH to RKE2 nodes from Rancher CLI - https://github.com/rancher/rancher/issues/35203
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cli/
- This functionality is the same as for RKE1, so no need to update any documentation, marked as done.

Added as of 5/9/22

[ ] Drain nodes on scale down- https://github.com/rancher/rancher/issues/35274
- Current docs links:
  - Could not find docs specifically mentioning this feature for RKE1 or RKE2
- This should probably be added to "Nodes and Node Pools" () section mentioned in "General Documentation" section.
- Engineering expert: @jakefhyde
[ ] Self-healing node pools- https://github.com/rancher/rancher/issues/35275
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/#about-node-auto-replace
- This is for RKE1 and the whole docs page is listed in "General Documentation" to be updated for RKE2.
- Engineering expert: @paynejacob
[ ] vSphere version pinning- https://github.com/rancher/rancher/issues/35474
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/vsphere/out-of-tree/
- This documentation seems to be RKE1-specific. For RKE2, vSphere Cloud Provider must be enabled and configured at cluster creation and vSphere charts are installed automatically (shouldn't follow the steps to install them from Apps & Marketplace). CPI/CSI charts are tied to selected k8s version and are automatically upgraded as needed with k8s version is upgraded for the cluster.
  - @slickwarren, since you were testing the linked issue, could you please confirm this is the actual behavior (in terms for setting up vSphere differences for RKE2 vs. the documentation linked)
[x] ~~Terraform provider updates- https://github.com/rancher/terraform-provider-rancher2/issues/799~~
- Terraform docs are separate and were updated as part of implementing these features in Terraform.
[x] IPv6 dual-stack (front-end addition) - https://github.com/rancher/dashboard/issues/4550
- Current docs links:
  - No Rancher documentation found; RKE1 documentation exists (https://rancher.com/docs/rke/latest/en/config-options/dual-stack/), but doesn't cover Rancher functionality around this
- IPv6 should be mentioned on https://rancher.com/docs/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/#container-network-provider, specifics as per the description on https://github.com/rancher/dashboard/issues/4550. Note that IPv6 dual-stack is supported for CNIs other than Cilium and Multus,Cilium; it's just Cilium requires additional parameter to be set for which UI provides a checkbox.
- Associated PR: https://github.com/rancher/docs/pull/4089
[x] ~~Scale down individual node - https://github.com/rancher/dashboard/issues/4446~~
- Current docs links:
  - https://rancher.com/docs/rancher/v2.6/en/cluster-admin/nodes/#deleting-a-node
- There shouldn't be anything to do for this specifically as "Nodes and Node Pools" section to be created for RKE2 per "General Documentation" section should contain "Deleting a Node" section explaining this feature.

BELOW ARE TO BE COMPLETED

Windows:

[ ] Windows - CIS Scans - https://github.com/rancher/windows/issues/107
[ ] Windows - Istio - https://github.com/rancher/windows/issues/108
[ ] Windows - CNI - Calico - PNI Support - https://github.com/rancher/windows/issues/106
[ ] Windows - RKE2 upgrade - https://github.com/rancher/windows/issues/76
[ ] Windows - Logging / Alerting / Monitoring

btat commented 2 years ago

Reopening as this got automatically closed through a keyword in rancher/docs#4075

slickwarren commented 2 years ago

vSphere version pinning- https://github.com/rancher/rancher/issues/35474
Current docs links:
https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/vsphere/out-of-tree/
This documentation seems to be RKE1-specific. For RKE2, vSphere Cloud Provider must be enabled and configured at cluster creation and vSphere charts are installed automatically (shouldn't follow the steps to install them from Apps & Marketplace). CPI/CSI charts are tied to selected k8s version and are automatically upgraded as needed with k8s version is upgraded for the cluster.
@slickwarren, since you were testing the linked issue, could you please confirm this is the actual behavior (in terms for setting up vSphere differences for RKE2 vs. the documentation linked)

yes I agree, this would need to be updated for rke2 and Sowmya's post is correct. for rke2, you would need to follow the instructions wen selecting the vsphere cloud provider option when provisioning the cluster, which will install the CPI/CSI charts during provisioning. Manually installing the charts after the cluster is in an active state is not supported for rke2.

I also noticed the docs have 6.7u3 listed as supported, but that has also been deprecated.

rancher / rancher-docs