mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-27 05:28:22 +00:00
Add v2.14 preview docs (#2212)
This commit is contained in:
Lucas Saintarbor
+65
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Access Clusters
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/access-clusters"/>
|
||||
</head>
|
||||
|
||||
This section is about what tools can be used to access clusters managed by Rancher.
|
||||
|
||||
For information on how to give users permission to access a cluster, see the section on [adding users to clusters.](add-users-to-clusters.md)
|
||||
|
||||
For more information on roles-based access control, see [this section.](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)
|
||||
|
||||
For information on how to set up an authentication system, see [this section.](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)
|
||||
|
||||
## Clusters in Rancher UI
|
||||
|
||||
There are several paths to view and manage clusters through the Rancher UI.
|
||||
|
||||
### Clusters Page
|
||||
|
||||
You can access the **Clusters** page from the **☰** menu:
|
||||
|
||||
1. Click **☰**.
|
||||
1. Select **Cluster Management**.
|
||||
|
||||
You can also access the **Clusters** page by clicking the **Manage** button above the clusters table on the Rancher UI **Home** page.
|
||||
|
||||
On the **Clusters** page, select **⁝** at the end of each row to view a submenu with the following options:
|
||||
|
||||
* [Kubectl Shell](use-kubectl-and-kubeconfig.md)
|
||||
* Download KubeConfig
|
||||
* Copy KubeConfig to Clipboard
|
||||
* Edit Config
|
||||
* View YAML
|
||||
* Download YAML
|
||||
|
||||
### Cluster Dashboard
|
||||
|
||||
On the **Clusters** page, select the **Explore** button at the end of each row to view that cluster's **Cluster Dashboard**. You can also view the dashboard by clicking the name of a cluster in the table, then clicking the **Explore** buttton on the **Cluster** page.
|
||||
|
||||
The **Cluster Dashboard** is also accessible from the Rancher UI **Home** page, by clicking on the name of a cluster.
|
||||
|
||||
You can also access the **Cluster Dashboard** from the **☰** in the top navigation bar:
|
||||
|
||||
1. Click **☰**.
|
||||
1. Select the name of a cluster from the **Explore Cluster** menu option.
|
||||
|
||||
The **Cluster Dashboard** lists information about a specific cluster, such as number of nodes, memory usage, events, and resources.
|
||||
|
||||
## kubectl
|
||||
|
||||
You can use the Kubernetes command-line tool, [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/), to manage your clusters. You have two options for using kubectl:
|
||||
|
||||
- **Rancher kubectl shell:** Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part. For more information, see [Accessing Clusters with kubectl Shell](use-kubectl-and-kubeconfig.md).
|
||||
- **Terminal remote connection:** You can also interact with your clusters by installing [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your local desktop and then copying the cluster's kubeconfig file to your local `~/.kube/config` directory. For more information, see [Accessing Clusters with kubectl and a kubeconfig File](use-kubectl-and-kubeconfig.md).
|
||||
|
||||
## Rancher CLI
|
||||
|
||||
You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI](../../../../reference-guides/cli-with-rancher/cli-with-rancher.md). This CLI tool can interact directly with different clusters and projects or pass them `kubectl` commands.
|
||||
|
||||
## Rancher API
|
||||
|
||||
Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an [API key](../../../../reference-guides/user-settings/api-keys.md). To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on **View in API** for any Rancher UI object.
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Adding Users to Clusters
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters"/>
|
||||
</head>
|
||||
|
||||
To provide a user access to view certain cluster-level resources and create new projects, assign the user a **Cluster Membership**. Cluster members can create projects and manage resources in those projects. However, not all resources, namespaces and workloads in a cluster are accessible by cluster members.
|
||||
|
||||
:::tip
|
||||
|
||||
Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members](../../../new-user-guides/add-users-to-projects.md) instead.
|
||||
|
||||
:::
|
||||
|
||||
There are two contexts where you can add cluster members:
|
||||
|
||||
- Adding Members to a New Cluster
|
||||
|
||||
You can add members to a cluster as you create it (recommended if possible).
|
||||
|
||||
- [Adding Members to an Existing Cluster](#editing-cluster-membership)
|
||||
|
||||
You can always add members to a cluster after a cluster is provisioned.
|
||||
|
||||
## Editing Cluster Membership
|
||||
|
||||
Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster you want to add members to and click **⋮ > Edit Config**.
|
||||
1. In the **Member Roles** tab, click **Add Member**.
|
||||
1. Search for the user or group that you want to add to the cluster.
|
||||
|
||||
:::note Notes:
|
||||
|
||||
- At least 2 characters must be typed in the search box for results to appear.
|
||||
- Users can be searched based on their username or display name.
|
||||
- Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive.
|
||||
|
||||
:::
|
||||
|
||||
If external authentication is configured:
|
||||
|
||||
- Rancher returns users from your [external authentication](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md) source as you type.
|
||||
|
||||
:::note Using AD but can't find your users?
|
||||
|
||||
There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5](../../../new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md).
|
||||
|
||||
:::
|
||||
|
||||
- A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of.
|
||||
|
||||
:::note
|
||||
|
||||
If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md#external-authentication-configuration-and-principal-users).
|
||||
|
||||
:::
|
||||
|
||||
1. Assign the user or group **Cluster** roles.
|
||||
|
||||
[What are Cluster Roles?](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
|
||||
|
||||
:::tip
|
||||
|
||||
For Custom Roles, you can modify the list of individual roles available for assignment.
|
||||
|
||||
- To add roles to the list, [Add a Custom Role](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md).
|
||||
- To remove roles from the list, [Lock/Unlock Roles](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md).
|
||||
|
||||
:::
|
||||
|
||||
**Result:** The chosen users are added to the cluster.
|
||||
|
||||
- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user.
|
||||
- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles.
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: How the Authorized Cluster Endpoint Works
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint"/>
|
||||
</head>
|
||||
|
||||
This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for [how to set up kubectl to directly access a cluster.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
|
||||
### About the Kubeconfig File
|
||||
|
||||
The kubeconfig file is used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients).
|
||||
|
||||
The kubeconfig file and its contents are specific to each cluster. It can be downloaded from the **Clusters** page in Rancher:
|
||||
|
||||
1. Click **☰** in the top left corner.
|
||||
1. Select **Cluster Management**.
|
||||
1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row.
|
||||
1. Select **Download KubeConfig** from the submenu.
|
||||
|
||||
You need a separate kubeconfig file for each cluster that you have access to in Rancher.
|
||||
|
||||
After you download the kubeconfig file, you are able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
|
||||
|
||||
If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](../../../../reference-guides/cli-with-rancher/rancher-cli.md) to be present in your PATH.
|
||||
|
||||
### Two Authentication Methods for RKE Clusters
|
||||
|
||||
If the cluster is not an [RKE cluster,](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster.
|
||||
|
||||
For RKE clusters, the kubeconfig file allows you to be authenticated in two ways:
|
||||
|
||||
- **Through the Rancher server authentication proxy:** Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access.
|
||||
- **Directly with the downstream cluster's API server:** RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the `kube-api-auth` microservice) that Rancher set up.
|
||||
|
||||
This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.
|
||||
|
||||
To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
|
||||
These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.
|
||||
|
||||
### About the kube-api-auth Authentication Webhook
|
||||
|
||||
The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the [authorized cluster endpoint](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint). When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook.
|
||||
|
||||
During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens.
|
||||
|
||||
The scheduling rules for `kube-api-auth` are listed below:
|
||||
|
||||
| Component | nodeAffinity nodeSelectorTerms | nodeSelector | Tolerations |
|
||||
| -------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
|
||||
| kube-api-auth | `beta.kubernetes.io/os:NotIn:windows`<br/>`node-role.kubernetes.io/controlplane:In:"true"` | none | `operator:Exists` |
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: "Access a Cluster with Kubectl and kubeconfig"
|
||||
description: "Learn how you can access and manage your Kubernetes clusters using kubectl with kubectl Shell or with kubectl CLI and kubeconfig file. A kubeconfig file is used to configure access to Kubernetes. When you create a cluster with Rancher, it automatically creates a kubeconfig for your cluster."
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig"/>
|
||||
</head>
|
||||
|
||||
This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.
|
||||
|
||||
For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/).
|
||||
|
||||
### Accessing Clusters with kubectl Shell in the Rancher UI
|
||||
|
||||
You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster you want to access with kubectl and click **Explore**.
|
||||
1. In the top navigation menu, click the **Kubectl Shell** button. Use the window that opens to interact with your Kubernetes cluster.
|
||||
|
||||
### Accessing Clusters with kubectl from Your Workstation
|
||||
|
||||
This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.
|
||||
|
||||
This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
|
||||
:::
|
||||
|
||||
1. Click **☰** in the top left corner.
|
||||
1. Select **Cluster Management**.
|
||||
1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row.
|
||||
1. Select **Download KubeConfig** from the submenu.
|
||||
1. Save the YAML file on your local computer. Move the file to `~/.kube/config`. Note: The default location that kubectl uses for the kubeconfig file is `~/.kube/config`, but you can use any directory and specify it using the `--kubeconfig` flag, as in this command:
|
||||
```
|
||||
kubectl --kubeconfig /custom/path/kube.config get pods
|
||||
```
|
||||
1. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.
|
||||
|
||||
|
||||
### Note on Resources Created Using kubectl
|
||||
|
||||
Rancher will discover and show resources created by `kubectl`. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.
|
||||
|
||||
## Authenticating Directly with a Downstream Cluster
|
||||
|
||||
This section intended to help you set up an alternative method to access a [Rancher-launched cluster.](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)
|
||||
|
||||
This method is only available RKE2 and K3s clusters that have the [authorized cluster endpoint](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) enabled. When Rancher creates the cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to [this page](authorized-cluster-endpoint.md).
|
||||
|
||||
On RKE2 and K3s clusters, you need to [manually enable](../../kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#authorized-cluster-endpoint-support-for-rke2-and-k3s-clusters) authorized cluster endpoints.
|
||||
|
||||
We recommend that as a best practice, you should set up this method to access your RKE2 and K3s clusters, so that just in case you can’t connect to Rancher, you can still access the cluster.
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
The following steps assume that you have created a Kubernetes cluster and followed the steps to [connect to your cluster with kubectl from your workstation.](#accessing-clusters-with-kubectl-from-your-workstation)
|
||||
|
||||
:::
|
||||
|
||||
To find the name of the context(s) in your downloaded kubeconfig file, run:
|
||||
|
||||
```
|
||||
kubectl config get-contexts --kubeconfig /custom/path/kube.config
|
||||
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
|
||||
* my-cluster my-cluster user-46tmn
|
||||
my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn
|
||||
```
|
||||
|
||||
In this example, when you use `kubectl` with the first context, `my-cluster`, you will be authenticated through the Rancher server.
|
||||
|
||||
With the second context, `my-cluster-controlplane-1`, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE2/K3s cluster directly.
|
||||
|
||||
We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#architecture-for-an-authorized-cluster-endpoint-ace)
|
||||
|
||||
Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below.
|
||||
|
||||
When `kubectl` works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy.
|
||||
|
||||
### Connecting Directly to Clusters with FQDN Defined
|
||||
|
||||
If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named `<CLUSTER_NAME>-fqdn`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context.
|
||||
|
||||
Assuming the kubeconfig file is located at `~/.kube/config`:
|
||||
|
||||
```
|
||||
kubectl --context <CLUSTER_NAME>-fqdn get nodes
|
||||
```
|
||||
Directly referencing the location of the kubeconfig file:
|
||||
```
|
||||
kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-fqdn get pods
|
||||
```
|
||||
|
||||
### Connecting Directly to Clusters without FQDN Defined
|
||||
|
||||
If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named `<CLUSTER_NAME>-<NODE_NAME>`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context.
|
||||
|
||||
Assuming the kubeconfig file is located at `~/.kube/config`:
|
||||
```
|
||||
kubectl --context <CLUSTER_NAME>-<NODE_NAME> get nodes
|
||||
```
|
||||
Directly referencing the location of the kubeconfig file:
|
||||
```
|
||||
kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAME> get pods
|
||||
```
|
||||
Reference in New Issue
Block a user