search

rancher / rancher-docs

Rancher Documentation
https://ranchermanager.docs.rancher.com/
Apache License 2.0
59 stars 207 forks source link

[Rancher2] Clarify registered cluster docs #77

Open cbron opened 2 years ago

cbron commented 2 years ago
  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.

  1. 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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

/assign

divya-mohan0209 commented 2 years ago

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

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 commented 2 years ago

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 commented 2 years ago

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

deniseschannon commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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

wpwoodjr commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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:

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 commented 2 years ago

@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 commented 2 years ago

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 commented 1 year ago

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

Other things that have made it:

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

And in regards to the personas sections from https://github.com/rancher/docs/pull/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 commented 1 year ago

Sketching out table referenced in https://github.com/rancher/rancher-docs/issues/77#issuecomment-1245965052

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