mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 04:28:15 +00:00
Explain authorized cluster endpoints
This commit is contained in:
Catherine Luse
@@ -24,11 +24,13 @@ kubectl --kubeconfig /custom/path/kube.config get pods
|
||||
|
||||
## Accessing Rancher Launched Kubernetes clusters without Rancher server running
|
||||
|
||||
By default, all Rancher Launched Kubernetes clusters have [Authorized Cluster Endpoint]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled.
|
||||
|
||||
> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS.
|
||||
|
||||
By default, Rancher generates a kubeconfig file that will proxy through the Rancher server to connect to the Kubernetes API server on a cluster.
|
||||
|
||||
For [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters, which have [Authorized Cluster Endpoint]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster.
|
||||
|
||||
> **Note:** By default, all Rancher Launched Kubernetes clusters have [Authorized Cluster Endpoint]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled.
|
||||
For [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters that have the authorized cluster endpoint enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster.
|
||||
|
||||
To find the name of the context(s), run:
|
||||
|
||||
@@ -38,6 +40,9 @@ CURRENT NAME CLUSTER AUTHINFO N
|
||||
* my-cluster my-cluster user-46tmn
|
||||
my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn
|
||||
```
|
||||
For more information on how the authorized cluster endpoint works, refer to the [architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint)
|
||||
|
||||
We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
### Clusters with FQDN defined as an Authorized Cluster Endpoint
|
||||
|
||||
@@ -65,7 +70,9 @@ kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAM
|
||||
|
||||
### kube-api-auth
|
||||
|
||||
The `kube-api-auth` resource is deployed to provide the functionality for Authorized Cluster Endpoint.
|
||||
The `kube-api-auth` resource is deployed to provide the functionality for the [authorized cluster endpoint.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint)
|
||||
|
||||
The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the 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.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Rancher simplifies the creation of clusters by allowing you to create them throu
|
||||
|
||||
This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{<baseurl>}}/rancher/v2.x/en/overview/concepts) page.
|
||||
|
||||
For a conceptual overview of how the Rancher server provisions clusters, refer to the [architecture]({{<baseurl>}}/rancher/v2.x/en/overview/rancher-and-downstream) section.
|
||||
For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/)
|
||||
|
||||
## Cluster Creation Options
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@ There are two different agent resources deployed on Rancher managed clusters:
|
||||
- [cattle-cluster-agent](#cattle-cluster-agent)
|
||||
- [cattle-node-agent](#cattle-node-agent)
|
||||
|
||||
For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/)
|
||||
|
||||
### cattle-cluster-agent
|
||||
|
||||
The `cattle-cluster-agent` is used to connect to the Kubernetes API of [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters. The `cattle-cluster-agent` is deployed using a Deployment resource.
|
||||
|
||||
@@ -71,7 +71,15 @@ See the [RKE documentation on private registries]({{< baseurl >}}/rke/latest/en/
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. This is enabled by default, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. It is recommended to create an FQDN pointing to a load balancer which load balances across your nodes with the `controlplane` role. If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate which will be included in the generated kubeconfig to validate the certificate chain. See the [Kubeconfig Files]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API Keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/#creating-an-api-key) documentation for more information.
|
||||
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.
|
||||
|
||||
> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS.
|
||||
|
||||
This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates.
|
||||
|
||||
For more detail on how an authorized cluster endpoint works and why it is used, refer to the [architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/4-authorized-cluster-endpoint)
|
||||
|
||||
We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
### Advanced Cluster Options
|
||||
|
||||
|
||||
@@ -22,4 +22,5 @@ Rancher provides an intuitive user interface for DevOps engineers to manage thei
|
||||
|
||||
The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@ This section covers the following topics:
|
||||
- [Recommended Load Balancer Configuration for HA Installations](#recommended-load-balancer-configuration-for-ha-installations)
|
||||
- [Environment for HA Installations](#environment-for-ha-installations)
|
||||
- [Recommended Node Roles for HA Installations](#recommended-node-roles-for-ha-installations)
|
||||
- [Architecture for an Authorized Cluster Endpoint](#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
# Separation of Rancher and User Clusters
|
||||
|
||||
@@ -82,4 +83,10 @@ With that said, it is safe to use all three roles on three nodes when setting up
|
||||
|
||||
Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of user clusters.
|
||||
|
||||
For details on the recommended best practices for user clusters, refer to the [production checklist]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{<baseurl>}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability)
|
||||
For more best practices for user clusters, refer to the [production checklist]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production) or our [best practices guide.]({{<baseurl>}}/rancher/v2.x/en/best-practices/management/#tips-for-scaling-and-reliability)
|
||||
|
||||
# Architecture for an Authorized Cluster Endpoint
|
||||
|
||||
If you are using an [authorized cluster endpoint,]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the `controlplane` role.
|
||||
|
||||
If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate, which will be included in the generated kubeconfig file to validate the certificate chain. See the documentation on [kubeconfig files]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/#creating-an-api-key) for more information.
|
||||
@@ -1,26 +1,30 @@
|
||||
---
|
||||
title: Rancher Server Architecture
|
||||
title: Architecture
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This section focuses on the Rancher server and its components. The Rancher server includes all the software components used to manage the entire Rancher deployment.
|
||||
This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters.
|
||||
|
||||
- For the different ways that Rancher can be installed, refer to the [installation options section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/installation-options)
|
||||
- For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/architecture-recommendations)
|
||||
- For an explanation of how Rancher communicates with downstream Kubernetes clusters, refer to the section on [Rancher and downstream user clusters.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/rancher-and-downstream)
|
||||
The Rancher server includes all the software components used to manage the entire Rancher deployment.
|
||||
|
||||
For the different ways that Rancher can be installed, refer to the [installation options section.]({{<baseurl>}}/rancher/v2.x/en/overview/installation-options)
|
||||
|
||||
For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations)
|
||||
|
||||
> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{<baseurl>}}/rancher/v2.x/en/overview/concepts) page.
|
||||
|
||||
# Features of the Rancher API Server
|
||||
This section covers the following topics:
|
||||
|
||||
The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:
|
||||
|
||||
- **User management:** The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub.
|
||||
- **Authorization:** The Rancher API server manages access control and security policies.
|
||||
- **Managing projects:** A _project_ is a group of multiple namespaces and access control policies within a cluster.
|
||||
- **Tracking nodes:** The Rancher API server tracks identities of all the nodes in all clusters.
|
||||
- **Provisioning Kubernetes Clusters:** The Rancher API server can provision Kubernetes clusters. Rancher can also set up Kubernetes on existing nodes, or import existing Kubernetes clusters into Rancher.
|
||||
- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud.
|
||||
- [Rancher server architecture](#rancher-server-architecture)
|
||||
- [Features of the Rancher API server](#features-of-the-rancher-api-server)
|
||||
- [Rancher server components and source code](#rancher-server-components-and-source-code)
|
||||
- [Communicating with downstream user clusters](#communicating-with-downstream-user-clusters)
|
||||
- [The authentication proxy](#1-the-authentication-proxy)
|
||||
- [Cluster controllers and cluster agents](#2-cluster-controllers-and-cluster-agents)
|
||||
- [Node agents](#3-node-agents)
|
||||
- [Authorized cluster endpoint](#4-authorized-cluster-endpoint)
|
||||
- [Important files](#important-files)
|
||||
- [Tools for provisioning Kubernetes clusters](#tools-for-provisioning-kubernetes-clusters)
|
||||
|
||||
# Rancher Server Architecture
|
||||
|
||||
@@ -30,13 +34,28 @@ The figure below illustrates the high-level architecture of Rancher 2.x. The fig
|
||||
|
||||
For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) for running your workloads.
|
||||
|
||||
|
||||
|
||||
You can install Rancher on a single node, or on a high-availability Kubernetes cluster.
|
||||
|
||||
A single-node installation is recommended for development and testing purposes, and a high-availability installation is recommended for production.
|
||||
|
||||
### Rancher Server Components
|
||||
The diagram below shows how users can manipulate both [Rancher-launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters and [hosted Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) clusters through Rancher's authentication proxy:
|
||||
|
||||
<figcaption>Manipulating Clusters through Rancher's Authentication Proxy</figcaption>
|
||||
|
||||
|
||||
|
||||
### Features of the Rancher API Server
|
||||
|
||||
The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:
|
||||
|
||||
- **User management:** The Rancher API server [manages user identities]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) that correspond to external authentication providers like Active Directory or GitHub.
|
||||
- **Authorization:** The Rancher API server manages [access control]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/) and [security]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/) policies.
|
||||
- **Managing projects:** A [project]({{<baseurl>}}/rancher/v2.x/en/project-admin/) is a group of multiple namespaces and access control policies within a cluster.
|
||||
- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/nodes/) in all clusters.
|
||||
- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/) on existing nodes, or [import existing Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) into Rancher.
|
||||
- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) and [persistent storage]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) in the cloud.
|
||||
|
||||
### Rancher Server Components and Source Code
|
||||
|
||||
This diagram shows each component that the Rancher server is composed of:
|
||||
|
||||
@@ -50,4 +69,113 @@ The GitHub repositories for each component of Rancher can be found at the follow
|
||||
- [Norman,](https://github.com/rancher/norman) Rancher's API framework
|
||||
- [Types](https://github.com/rancher/types)
|
||||
- [Rancher CLI](https://github.com/rancher/cli)
|
||||
- [Catalog applications](https://github.com/rancher/helm)
|
||||
- [Catalog applications](https://github.com/rancher/helm)
|
||||
|
||||
# Communicating with Downstream User Clusters
|
||||
|
||||
This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services.
|
||||
|
||||
<figcaption>Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. [The Authentication Proxy](#1-the-authentication-proxy)
|
||||
2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents)
|
||||
3. [Node Agents](#3-node-agents)
|
||||
4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)
|
||||
|
||||
### 1. The Authentication Proxy
|
||||
|
||||
In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) which provides an identity for processes that run in a pod.
|
||||
|
||||
By default, Rancher generates a [kubeconfig file]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/kubeconfig/) that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (`kube_config_rancher-cluster.yml`) contains full access to the cluster.
|
||||
|
||||
### 2. Cluster Controllers and Cluster Agents
|
||||
|
||||
Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server.
|
||||
|
||||
There is one cluster controller and one cluster agent for each downstream cluster.
|
||||
|
||||
By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a [node agent](#3-node-agents) instead.
|
||||
|
||||
The cluster controller is a component of the Rancher server performs the following tasks:
|
||||
|
||||
- Configures access control policies to clusters and projects
|
||||
- Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE
|
||||
|
||||
The cluster agent, also called `cattle-cluster-agent`, is a component that runs in a downstream user cluster. It performs the following tasks:
|
||||
|
||||
- Connects to the Kubernetes API of Rancher-launched Kubernetes clusters
|
||||
- Manages workloads, pod creation and deployment within each cluster
|
||||
- Applies the roles and bindings defined in each cluster's global policies
|
||||
- Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health
|
||||
|
||||
### 3. Node Agents
|
||||
|
||||
If the cluster agent (also called `cattle-cluster-agent`) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.
|
||||
|
||||
The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.
|
||||
|
||||
### 4. Authorized Cluster Endpoint
|
||||
|
||||
An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy.
|
||||
|
||||
> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for imported clusters, or for clusters in a hosted Kubernetes provider, such as Amazon's EKS.
|
||||
|
||||
There are two main reasons why a user might need the authorized cluster endpoint:
|
||||
|
||||
- To access a downstream user cluster while Rancher is down
|
||||
- To reduce latency in situations where the Rancher server and downstream cluster are separated by a long distance
|
||||
|
||||
The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the 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.
|
||||
|
||||
Like the authorized cluster endpoint, the `kube-api-auth` authentication service is also only available for Rancher-launched Kubernetes clusters.
|
||||
|
||||
> **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, also lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from China to the Rancher server in the United States, then be proxied back to China, where the downstream user cluster is. The geographical distance may cause significant latency. To reduce the latency, which Alice can reduce by using the authorized cluster endpoint.
|
||||
|
||||
With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`.
|
||||
|
||||
You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the [kubeconfig file]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/kubeconfig) documentation.
|
||||
|
||||
# Important Files
|
||||
|
||||
The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down.
|
||||
- `rancher-cluster.rkestate`: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher.
|
||||
|
||||
For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation.
|
||||
|
||||
# Tools for Provisioning Kubernetes Clusters
|
||||
|
||||
The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.
|
||||
|
||||
### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider
|
||||
|
||||
Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.
|
||||
|
||||
Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine)
|
||||
|
||||
### Rancher Launched Kubernetes for Custom Nodes
|
||||
|
||||
When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster.
|
||||
|
||||
Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke)
|
||||
|
||||
### Hosted Kubernetes Providers
|
||||
|
||||
When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.
|
||||
|
||||
Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine)
|
||||
|
||||
### Imported Kubernetes Clusters
|
||||
|
||||
In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.
|
||||
@@ -3,6 +3,8 @@ title: Kubernetes Concepts
|
||||
weight: 4
|
||||
---
|
||||
|
||||
This page explains concepts related to Kubernetes that are important for understanding how Rancher works. The descriptions below provide a simplified interview of Kubernetes components. For more details, refer to the [official documentation on Kubernetes components.](https://kubernetes.io/docs/concepts/overview/components/)
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [About Docker](#about-docker)
|
||||
|
||||
@@ -21,10 +21,10 @@ Basic options for installing Rancher include the following:
|
||||
Level of Internet Access | Single Node Instructions | HA Instructions
|
||||
---------------------------|-----------------------------|------------------
|
||||
With direct access to the Internet | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/ha/)
|
||||
Behind an HTTP proxy | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/proxy/) | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy)
|
||||
Behind an HTTP proxy | These [docs,]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) plus this [configuration]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/proxy/) | These [docs,]({{<baseurl>}}/rancher/v2.x/en/installation/ha/) plus this [configuration]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#http-proxy)
|
||||
In an air gap environment | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap/) | [Docs]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap/)
|
||||
|
||||
# More Options
|
||||
# More Options for HA Installations
|
||||
|
||||
Refer to the [Helm chart options]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/) for details on installing HA Rancher with other configurations, including:
|
||||
|
||||
@@ -32,10 +32,14 @@ Refer to the [Helm chart options]({{<baseurl>}}/rancher/v2.x/en/installation/ha/
|
||||
- With [TLS termination on a load balancer]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination)
|
||||
- With a [custom Ingress]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#customizing-your-ingress)
|
||||
|
||||
RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{<baseurl>}}/rke/latest/en/config-options/) for the full list of options and capabilities.
|
||||
# More Options for Single Node Installations
|
||||
|
||||
Refer to the [single node installation docs]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) for details other configurations including:
|
||||
|
||||
- With [API auditing to record all transactions]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/#api-audit-log)
|
||||
- With an [external load balancer]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/)
|
||||
- With a [persistent data store]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/#persistent-data)
|
||||
- With a [persistent data store]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/#persistent-data)
|
||||
|
||||
# More Kubernetes Options
|
||||
|
||||
RKE also has many configuration options for customizing the Kubernetes cluster to suit your specific environment. Please see the [RKE Documentation]({{<baseurl>}}/rke/latest/en/config-options/) for the full list of options and capabilities.
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
title: Rancher and Downstream User Clusters
|
||||
weight: 5
|
||||
---
|
||||
|
||||
This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services.
|
||||
|
||||
- [How Rancher Communicates with Downstream User Clusters](#how-rancher-communicates-with-downstream-user-clusters)
|
||||
- [Authentication Proxy](#authentication-proxy)
|
||||
- [Connecting to a Cluster without the Rancher UI](#connecting-to-a-cluster-without-the-rancher-ui)
|
||||
- [How Rancher Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters)
|
||||
|
||||
# How Rancher Communicates with Downstream User Clusters
|
||||
|
||||
Rancher communicates with downstream user clusters by using three types of components: the cluster controller, the cluster agent, and the node agent. These components are used for provisioning and managing Kubernetes clusters.
|
||||
|
||||
The cluster controller and cluster agents implement the business logic required to manage Kubernetes clusters.
|
||||
|
||||
Rancher installs the `cattle-node-agent` on each node in downstream user clusters in order to manage them.
|
||||
|
||||
<figcaption>Cluster Controller, Cluster Agent, and Node Agents Allow Rancher to Control Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. Let's say a user, Bob, wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
2. Each downstream user cluster has a cluster agent, which opens a tunnel connecting the user cluster with Rancher's corresponding cluster controller.
|
||||
|
||||
3. By default, the cluster controller connects to the cluster agent. If the cluster agent is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.
|
||||
|
||||
4. Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in China. A user, Alice, lives in China. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but she may experience latency due to the distance between US and China. To reduce latency, she can use Rancher's authorized cluster endpoint feature. By default, an authorized cluster endpoint is enabled, which allows Alice to be authenticated by calling the Kubernetes API server of the user cluster, without going through Rancher's authentication proxy. When Alice uses kubectl to access the user cluster, the cluster's Kubernetes API server authenticates Alice by using the `kube-api-auth` service as a webhook. The `kube-api-auth` authentication service and authorized cluster endpoint are only available for Rancher-launched Kubernetes clusters.
|
||||
|
||||
### The Cluster Controller
|
||||
|
||||
The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions:
|
||||
|
||||
- Configures access control policies to clusters and projects
|
||||
- Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE
|
||||
|
||||
### The Cluster Agent
|
||||
|
||||
The `cattle-cluster-agent` is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The `cattle-cluster-agent` is deployed on the Rancher server using a deployment resource.
|
||||
|
||||
The cluster agent implements the logic required for the corresponding downstream user cluster. It performs the following activities:
|
||||
|
||||
- Manages workloads, pod creation and deployment within each cluster
|
||||
- Applies the roles and bindings defined in each cluster's global policies
|
||||
- Communicates between clusters and Rancher server about events, stats, node info, and health
|
||||
|
||||
### The Node Agent
|
||||
|
||||
The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.
|
||||
|
||||
The `cattle-node-agent` is also used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when `cattle-cluster-agent` is unavailable.
|
||||
|
||||
# Authentication Proxy
|
||||
|
||||
The _authentication proxy_ forwards all Kubernetes API calls. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), which provides an identity for processes that run in a pod.
|
||||
|
||||
### Connecting to a Cluster without the Rancher UI
|
||||
|
||||
By default, Rancher generates a kubeconfig file that will proxy through the Rancher server to connect to the Kubernetes API server on a cluster.
|
||||
|
||||
For [Rancher launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) clusters, which have an [authorized cluster endpoint]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#authorized-cluster-endpoint) enabled, Rancher generates extra context(s) in the kubeconfig file in order to connect directly to the cluster. The authorized cluster endpoint is enabled by default.
|
||||
|
||||
When you want to use kubectl to access this cluster without Rancher, you will need to use a context defined in this kubeconfig file. This file has the credentials for `kubectl` and `helm`.
|
||||
|
||||
The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint.
|
||||
|
||||
The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_rancher-cluster.yml`: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `rancher-cluster.rkestate`: The Kubernetes Cluster State file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher.
|
||||
|
||||
For more information on connecting to a cluster without the Rancher UI, refer to the [kubeconfig file]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/kubeconfig/) documentation.
|
||||
|
||||
# How Rancher Provisions Kubernetes Clusters
|
||||
|
||||
The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.
|
||||
|
||||
### Rancher Launched Kubernetes for Hodes Hosted in an Infrastructure Provider
|
||||
|
||||
Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.
|
||||
|
||||
Rancher provisions this type of cluster using [RKE](https://github.com/rancher/rke) and [docker-machine.](https://github.com/rancher/machine)
|
||||
|
||||
### Rancher Launched Kubernetes for Custom Nodes
|
||||
|
||||
When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster.
|
||||
|
||||
Rancher provisions this type of cluster using [RKE.](https://github.com/rancher/rke)
|
||||
|
||||
### Hosted Kubernetes Providers
|
||||
|
||||
When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.
|
||||
|
||||
Rancher provisions this type of cluster using [kontainer-engine.](https://github.com/rancher/kontainer-engine)
|
||||
|
||||
### Imported Kubernetes Clusters
|
||||
|
||||
In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 79 KiB After Width: | Height: | Size: 127 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 48 KiB After Width: | Height: | Size: 70 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 97 KiB |
Reference in New Issue
Block a user