[Rancher2] Clarify registered cluster docs

[cbron]

1. Imported vs registered

The cluster registration feature replaced the feature to import clusters.

This isn't correct, both still exist. Registering means that we tie in closer with the cloud API's and can fully manage a cluster such as EKS. Importing means taking any generic cluster and adding it to rancher with very basic functionality. I think it would be helpful to list which clusters can be registered: AKS, GKE, EKS. Then maybe k3s....

I'm not sure to what extent k3s is registered, further below we have: "When you delete a cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.", is that true for k3s ? Reading that sentence, I would assume it means deleting a "registered" k3s cluster in rancher won't delete the underlying cluster, but I doubt that is the behavior. @cwayne18 ? Might need to rethink how we position k3s as a registered cluster.

2. Cluster Type Table

This has a section called: "NON-EKS OR GKE REGISTERED CLUSTERS", which potentially should include AKS. But looking further at that column I don't think it makes sense in general. The only difference between it and "Other" is "Ability to backup and restore Rancher-launched clusters" but if they are registered then they aren't rancher-launched. It also doesn't have clone checked, so maybe there is a difference there, that I'm not sure.

[deniseschannon]

This is a major issue where we shouldn't have replaced the page but it's not distinguished as 2 sets of clusters.

Import is really import ANY cluster into Rancher to allow to start leveraging Rancher features for individual clusters but you continue to manage the Kubernetes cluster outside of Rancher

Register is taking a Kubernetes cluster into Rancher and then Rancher would manage the the Kubernetes cluster as well.

Most likely in the docs we need to differentiate between managing a Kubernetes cluster vs. using Rancher to manage workloads on your Kubernetes cluster

[deniseschannon]

For example - this page should be include as it's still applicable:
https://rancher.com/docs/rancher/v2.0-v2.4/en/cluster-provisioning/imported-clusters/

[divya-mohan0209]

/assign

[divya-mohan0209]

@deniseschannon @cbron from the above discussion, would it be fair for me to summarize the scope of work as below,

• Distinction between importing and registering a K8s cluster is incorrectly stated in this doc. This needs modification to reflect it correctly.
• In the same doc, we also need to list out which clusters can be registered.
• On this page we need to clarify whether AKS fits the bill for inclusion under NON-EKS OR GKE REGISTERED CLUSTER and if it does, modify it appropriately.

Given the above, would it make sense to revisit the cluster provisioning page in its entirety from a technical perspective across ALL the versions and revise the content wherever erroneous on the 2.5 & 2.6 ones?

[deniseschannon]

Yes, I think we should review cluster provisioning as recently I realized we should do the following within the cluster provisioning part:

Layout the difference between the "admin" side of a k8s cluster - aka who is managing the k8s health of the cluster vs. the "dev/workload" side of a k8s cluster - aka who is using the k8s cluster to deploy apps/workloads/resources onto it.

After describing that difference, then for the provisioning part we need to clearly distinguish the difference of the clusters that are brought into Rancher based on
who is managing the admin side of k8s as well as whether or not the end user is expected to continue managing the admin side of teh cluster through rancher or outside of rancher

I think this table tries to do all of that, but it's not clear to a new user the difference between managing the admin side vs. dev side. https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/#cluster-management-capabilities-by-cluster-type

I could see some kind of table that describes the difference between these 3 key points:

1. Who/where are the nodes created
2. Who creates the k8s cluster components (api-server, etc)
3. After the k8s cluster is created, where to manage it (through Rancher, outside of Rancher, etc)

high level summary would be something like:
Node provisioned clusters

1. Rancher triggers to request the cloud infra provider to create the node (no k8s on it)
2. Rancher creates the k8s cluster components
3. Through Rancher UI, end user manages changes to the k8s cluster components

Custom clusters

1. End user creates the nodes (either bare metal server (most common use case) or a VM through a cloud inrfra)
2. Rancher creates the k8s cluster components by running a docker container
3. Through Rancher UI, end user manages changes to the k8s cluster components

hosted providers

1. rancher requests the cloud infra to create the k8s cluster and the cloud infra provider creates the nodes
2. hosted provider creates the k8s cluster components
3. hosted provider manages the health of the k8s cluster components, but in 2.6, the end user can manage the k8s cluster through Rancher or through the hosted provider UI (this would need to be double checked but i think we fixed this use case). in 2.5, the end user is expected to manage the k8s cluster through Rancher

imported clusters

1. end user creates the nodes
2. end user creates the k8s cluster components
3. end user manages the cluser components outside of rancher. note: there is one caveat for k3s/rke2 clusters that rancher supports the ability to update the k8s version through Rancher

register hosted provider clusters

1. end user requests the cloud infra to create the k8s cluster and the cloud infra provider creates the nodes
2. hosted provider creates the k8s cluster components
3. registering it with Rancher will convert the cluster from a typical "imported" cluster to becoming a "hosted provider" cluster where the user can manage the cluster through the Rancher UI instead of only outside of rancher.

For any/all clusters that are brought into Rancher, you are able to leverage the "workload" side of the cluster and use the features of rancher on top of the clusters.

@cbron @snasovich could both of you quickly review to see if how i've described it is accurate?

@divya-mohan0209 I wrote this up very quickly, so please excuse typos/grammar, but let me know if the concept/idea of what I'm trying to differentiate makes sense or not

[divya-mohan0209]

Yep, it makes total sense to me. However scoping out the work that needs to be done wrt writing the above,

• Would we want to pursue a written/tabular format for readability purposes?
• Should this be staged as a change i.e. first on 2.5 and then 2.6? Or do we want to merge across both the versions together?

[deniseschannon]

Would we want to pursue a written/tabular format for readability purposes?

I'll leave it to you to decide what's best!

Should this be staged as a change i.e. first on 2.5 and then 2.6? Or do we want to merge across both the versions together?

2.6 and then 2.5 would be fine with me

[divya-mohan0209]

So, I revisited this today & here's what I think would be our best bet. Please let me know if this makes sense since I do tend to lean towards too much information as opposed to too little.
--> We need to have a separate page (somewhere within the cluster management) detailing each cluster type because this is something that is referenced in the cluster admin page(https://rancher.com/docs/rancher/v2.6/en/cluster-admin/), as well. We don't have this currently, atleast not in the way that's described above.
--> We can then use that as a central link to both the tables in cluster management & cluster provisioning tables.

[deniseschannon]

@divya-mohan0209 I'm the believer that more is better than less as someone out there will appreciate it. Your suggestions sound good and a beast way to describe them.

[divya-mohan0209]

Sure, okie dokie. Will get cracking on this then and have something for y’all to review by next week!

[wpwoodjr]

Please also look at https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-eks-and-gke-clusters where it does not mention AKS clusters (my understanding is that AKS clusters can be registered too):

Additional Features for Registered EKS and GKE Clusters

Registering an Amazon EKS cluster or GKE cluster allows Rancher to treat it as though it were created in Rancher.

Amazon EKS clusters and GKE clusters can now be registered in Rancher. For the most part, these registered clusters are treated the same way as clusters created in the Rancher UI, except for deletion.

When you delete an EKS cluster or GKE cluster that was created in Rancher, the cluster is destroyed. When you delete a cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.

The capabilities for registered clusters are listed in the table on this page.

[wpwoodjr]

Also please see https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/ where it doesn't mention AKS:

1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

[jtravee]

https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/

Thanks for your contribution. AKS came along a little later and can be registered as well, as you noted.

@divya-mohan0209, you could add "AKS" to the verbiage, tables, and sections wherein we only mention EKS and GKE cluster registration in the links @wpwoodjr provided. Thanks!

[wpwoodjr]

I must admit after looking at this further I'm more confused than ever. Docs say:

Registered GKE and EKS [and AKS!] clusters have the same options available as GKE and EKS [and AKS!] clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

But what does this mean? I can't find anywhere that details the "options available". For instance, can a registered AKS cluster's version of Kubernetes be upgraded? Can the number of nodes be increased?

For an example of how confusing this is with regards to upgrading the Kubernetes version:

• Here it says the Kubernetes version is configurable in AKS: https://rancher.com/docs/rancher/v2.6/en/cluster-admin/editing-clusters/aks-config-reference/#kubernetes-version
• Here it has a check mark next to "Editing and upgrading clusters" for EKS, GKE, and AKS clusters: https://rancher.com/docs/rancher/v2.6/en/cluster-admin/editing-clusters/
• Here it says "The options below are available only for Rancher-launched RKE Kubernetes clusters and Registered K3s Kubernetes clusters": https://rancher.com/docs/rancher/v2.6/en/cluster-admin/upgrading-kubernetes/#upgrading-the-kubernetes-version

I created an AKS cluster a year or so ago and was able to upgrade the Kubernetes version. So in a registered AKS cluster I should be able to upgrade the Kubernetes version, correct?

[thedadams]

@wpwoodjr Thanks for you feedback. I know the docs team is working to make these things as clear as possible. For now, I will try to clear a few things up.

Registered AKS clusters can be edited, upgraded, and configured just the same as AKS clusters provisioned from Rancher. You can upgrade the Kubernetes version (the versions are pulled from AKS dynamically based on the current version of the AKS cluster -- that is what the fist link you posted is indicating), add node pools, scale node pools, etc. The goal is anything that can be done in the AKS UI can also be done in the Rancher UI, but Rancher would obviously lag behind AKS slightly in implementing changes. A list of all the things that can be configured for an AKS cluster is here (this is essentially the first link you posted). Some of those things can't be changed after the cluster or node pool is created, but that would be an AKS restriction not a Rancher one.

As far as the third link you included, that is a little out of date. For example, the Kubernetes version of an imported RKE2 cluster can also be upgraded from Rancher. However, if you imported an AKS cluster as a generic cluster instead of registering it as an AKS cluster, then you would not be able to upgrade the Kubernetes version or configure the cluster really at all. Only by registering the cluster as an AKS cluster will you gain the additional functionality in Rancher.

[divya-mohan0209]

hello folks, I'm actively working on making this as clear as possible and should have something for y'all to review on Monday.

@jtravee : Noted, will incorporate the feedback above.

[martyav]

I was looking through backlog, and it seems that the changes from rancher/docs#3936 (minus the persona sections) have made the transfer over to our new repo.

Other things that have made it:

• The latest version of Registering Existing Clusters now mentions Azure, as suggested in this comment. However, the 2.6 page, which was the original concern, still needs updating. -- updated in #77 Addressing backlog issue about registered AKS clusters #518
• This comment was also successfully addressed in our docs for 2.6 and latest (2.7).
• Updated in #77 Part 2: Addressing backlog issue about imported registered RKE2 clusters #520 This page and the latest version both retain the problems noted:

As far as the third link you included, that is a little out of date. For example, the Kubernetes version of an imported RKE2 cluster can also be upgraded from Rancher. However, if you imported an AKS cluster as a generic cluster instead of registering it as an AKS cluster, then you would not be able to upgrade the Kubernetes version or configure the cluster really at all. Only by registering the cluster as an AKS cluster will you gain the additional functionality in Rancher.

However, we still need to address suggestions made in this issue thread:

• "The cluster registration feature replaced the feature to import clusters." verbiage remains in our docs, although in this comment is noted to be imprecise.
• This comment describing a table laying out differences between node-provisioned clusters, imported clusters, etc.

And in regards to the personas sections from rancher/docs#3936 not making the transfer -- imo we don't really need to explicitly describe personas anywhere in the docs. We write with the personas in mind but we don't address them in the third person, since they're our audience.

[martyav]

Sketching out table referenced in #77 (comment)

Cluster Type	Who Creates Cluster Nodes	Who Creates Cluster Components	Where to Manage Cluster
Node-provisioned clusters	Cloud infrastructure provider, as requested by Rancher.	Rancher	Rancher UI
Custom clusters	End user	Rancher	Rancher UI
Imported clusters	End user	End user	RKE: Outside of Rancher RKE2/K3s: Rancher UI
Cloud hosted clusters	Cloud infrastructure provider, as requested by Rancher.	Cloud provider	v2.5 Rancher UI. v2.6 and higher: Rancher UI or cloud host
Registered cloud hosted clusters	Cloud infrastructure provider, as requested by end user.	Cloud provider	Rancher UI