mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-24 20:18:18 +00:00
Revise/expand architecture page and conceptual docs
This commit is contained in:
Catherine Luse
@@ -8,44 +8,11 @@ aliases:
|
||||
- /rancher/v2.x/en/tasks/clusters/creating-a-cluster/
|
||||
---
|
||||
|
||||
## What's a Kubernetes Cluster?
|
||||
Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.
|
||||
|
||||
A cluster is a group of computers that work together as a single system.
|
||||
|
||||
A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations.
|
||||
|
||||
### Kubernetes Cluster Node Components
|
||||
|
||||
Each computing resource in a Kubernetes Cluster is called a _node_. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes.
|
||||
|
||||
#### etcd Nodes
|
||||
|
||||
[etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd) nodes run the etcd database. The etcd database component is a key value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management.
|
||||
|
||||
etcd is a distributed key value store, meaning it runs on multiple nodes so that there's always a backup available for fail over. Even though you can run etcd on a single node, you should run it on multiple nodes. We recommend 3, 5, or 7 etcd nodes for redundancy.
|
||||
|
||||
#### Control Plane Nodes
|
||||
|
||||
[Control plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles.
|
||||
|
||||
#### Worker Nodes
|
||||
|
||||
[Worker nodes](https://kubernetes.io/docs/concepts/architecture/nodes/) run:
|
||||
|
||||
- _Kubelets_: An agent that monitors the state of the node, ensuring your containers are healthy.
|
||||
- _Workloads_: The containers and pods that hold your apps, as well as other types of deployments.
|
||||
|
||||
Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads.
|
||||
|
||||
## Cluster Creation in Rancher
|
||||
|
||||
Now that you know what a Kubernetes Cluster is, how does Rancher fit in?
|
||||
|
||||
Rancher simplifies creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.
|
||||
|
||||
<br/>
|
||||
<sup>Rancher components used for provisioning/managing Kubernetes clusters.</sup>
|
||||
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.
|
||||
|
||||
## Cluster Creation Options
|
||||
|
||||
@@ -61,35 +28,46 @@ Options include:
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
### Hosted Kubernetes Cluster
|
||||
# Hosted Kubernetes Cluster
|
||||
|
||||
If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage a hosted cluster from the Rancher UI.
|
||||
|
||||
[Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters)
|
||||
[Hosted Kubernetes Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters)
|
||||
|
||||
### Rancher Launched Kubernetes
|
||||
# Rancher Launched Kubernetes
|
||||
|
||||
Alternatively, you can use Rancher to create a cluster on your own nodes, using [Rancher Kubernetes Engine (RKE)]({{< baseurl >}}/rke/latest/en/). RKE is Rancher’s own lightweight Kubernetes installer. In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. These nodes can either:
|
||||
The [Rancher Kubernetes Engine (RKE)]({{<baseurl>}}/rke/latest/en/) allows you to create a Kubernetes cluster on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer.
|
||||
|
||||
- Be provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers.
|
||||
- Be a prior existing node that's brought into the cluster by running a Rancher agent container on it.
|
||||
In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform.
|
||||
|
||||
[Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/)
|
||||
These nodes can be dynamically provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers.
|
||||
|
||||
#### Nodes Hosted by an Infrastructure Provider
|
||||
If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it.
|
||||
|
||||
Using Rancher, you can create pools of nodes based on a [node template]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers. The cloud providers available for creating a node template are decided based on the [node drivers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI. The benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher automatically replaces it, thus maintaining the expected cluster configuration.
|
||||
For more information, refer to the section on [RKE clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/)
|
||||
|
||||
[Nodes Hosted by an Infrastructure Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/)
|
||||
### Nodes Hosted by an Infrastructure Provider
|
||||
|
||||
#### Custom Nodes
|
||||
Using Rancher, you can create pools of nodes based on a [node template]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers.
|
||||
|
||||
You can bring any nodes you want to Rancher and use them to create a cluster. These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines.
|
||||
The benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher automatically replaces it, thus maintaining the expected cluster configuration.
|
||||
|
||||
[Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/)
|
||||
The cloud providers available for creating a node template are decided based on the [node drivers]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI.
|
||||
|
||||
### Import Existing Cluster
|
||||
For more information, refer to the section on [nodes hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/)
|
||||
|
||||
Users can import an existing Kubernetes cluster into Rancher. Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. All other Rancher features, including management of cluster, policy, and workloads, are available for imported clusters.
|
||||
### Custom Nodes
|
||||
|
||||
[Importing Existing Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/)
|
||||
You can bring any nodes you want to Rancher and use them to create a cluster. Clusters created with custom nodes are also called custom clusters.
|
||||
|
||||
These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines.
|
||||
|
||||
[Custom Nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/)
|
||||
|
||||
# Import Existing Cluster
|
||||
|
||||
Users can import an existing Kubernetes cluster into Rancher.
|
||||
|
||||
Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. All other Rancher features, including management of cluster, policy, and workloads, are available for imported clusters.
|
||||
|
||||
For more information, refer to the section on [importing existing clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/)
|
||||
|
||||
@@ -9,9 +9,9 @@ This procedure walks you through setting up a 3-node cluster with Rancher Kubern
|
||||
|
||||
> **Important:** The Rancher management server can only be run on an RKE-managed Kubernetes cluster. Use of Rancher on hosted Kubernetes or other providers is not supported.
|
||||
|
||||
> **Important:** For the best performance, 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.
|
||||
> **Important:** 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.
|
||||
|
||||
## Recommended Architecture
|
||||
We recommend the following configurations for the load balancer and Ingress controllers:
|
||||
|
||||
* DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
|
||||
* The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
|
||||
@@ -44,7 +44,7 @@ The following CLI tools are required for this install. Please make sure these to
|
||||
|
||||
[RKE add-on install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/)
|
||||
|
||||
> ##### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
> **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher helm chart to install HA Rancher. For details, see the [HA Install - Installation Outline]({{< baseurl >}}/rancher/v2.x/en/installation/ha/#installation-outline).
|
||||
>
|
||||
|
||||
@@ -22,4 +22,4 @@ 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.
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: Architecture Recommendations
|
||||
weight: 3
|
||||
---
|
||||
|
||||
This page describes our recommendations for how to install Rancher.
|
||||
|
||||
These recommendations focus on how to set up Rancher on a high-availability (HA) cluster. If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the node running Rancher should be [separate from downstream clusters.](#separation-of-rancher-and-user-clusters)
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Separation of Rancher and User Clusters](#separation-of-rancher-and-user-clusters)
|
||||
- [Why HA is Better for Rancher in Production](#why-ha-is-better-for-rancher-in-production)
|
||||
- [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)
|
||||
|
||||
# Separation of Rancher and User Clusters
|
||||
|
||||
A user cluster is a downstream Kubernetes cluster that runs your apps and services.
|
||||
|
||||
If you have a single node installation of Rancher, the node running the Rancher server should be separate from your downstream clusters.
|
||||
|
||||
In HA installations of Rancher, the Rancher server cluster should also be separate from the user clusters.
|
||||
|
||||
|
||||
|
||||
# Why HA is Better for Rancher in Production
|
||||
|
||||
We recommend installing the Rancher server on a three-node Kubernetes cluster for production, primarily because it protects the data stored on etcd. The Rancher server stores its data in etcd in both single-node and HA installations.
|
||||
|
||||
When Rancher is installed on a single node, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
By contrast, in the high-availability installation,
|
||||
|
||||
- The etcd data is replicated on three nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.
|
||||
- A load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure.
|
||||
- When one application server fails or becomes unavailable, the load balancer directs traffic to available servers using an algorithm. For example, the least connection method directs traffic to the service with the fewest active connections. The least connection method is indicated with the `least_conn` option in this [example]({{<baseurl>}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/) of how to configure an NGINX server as a basic layer 4 load balancer (TCP). The load balancer handles traffic so that each server can receive a manageable load.
|
||||
|
||||
# Recommended Load Balancer Configuration for HA Installations
|
||||
|
||||
We recommend the following configurations for the load balancer and Ingress controllers:
|
||||
|
||||
* The DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
|
||||
* The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
|
||||
* The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
|
||||
* The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
|
||||
|
||||
<figcaption>HA Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</figcaption>
|
||||
|
||||
<sup>HA Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers</sup>
|
||||
|
||||
# Environment for HA Installations
|
||||
|
||||
It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine, and the cluster should be dedicated only to run Rancher.
|
||||
|
||||
It is not recommended to install Rancher on top of a managed Kubernetes service such as Amazon’s EKS or Google Kubernetes Engine. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations.
|
||||
|
||||
# Recommended Node Roles for HA Installations
|
||||
|
||||
We recommend installing Rancher on a Kubernetes cluster in which each node has all three Kubernetes roles: etcd, controlplane, and worker.
|
||||
|
||||
### Comparing Node Roles for the Rancher Server Cluster and User Clusters
|
||||
|
||||
Our recommendation for node roles on the Rancher server cluster contrast with our recommendations for the downstream user clusters that run your apps and services. We recommend that each node in a user cluster should have a single role for stability and scalability.
|
||||
|
||||
|
||||
|
||||
Kubernetes only requires at least one node with each role and does not require nodes to be restricted to one role. However, for the clusters that run your apps, we recommend separate roles for each node so that workloads on worker nodes don't interfere with the Kubernetes master or cluster data as your services scale.
|
||||
|
||||
We recommend that downstream user clusters should have at least:
|
||||
|
||||
- **Three nodes with only the etcd role** to maintain a quorum if one node is lost, making the state of your cluster highly available
|
||||
- **Two nodes with only the controlplane role** to make the master component highly available
|
||||
- **One or more nodes with only the worker role** to run the Kubernetes node components, as well as the workloads for your apps and services
|
||||
|
||||
With that said, it is safe to use all three roles on three nodes when setting up the Rancher server because:
|
||||
|
||||
* It allows one `etcd` node failure.
|
||||
* It maintains multiple instances of the master components by having multiple `controlplane` nodes.
|
||||
* No other workloads than Rancher itself should be created on this cluster.
|
||||
|
||||
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)
|
||||
@@ -1,102 +1,53 @@
|
||||
---
|
||||
title: Architecture
|
||||
title: Rancher Server Architecture
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This section explains how Rancher interacts with the two fundamental technologies Rancher is built on: Docker and Kubernetes.
|
||||
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.
|
||||
|
||||
## Docker
|
||||
- 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)
|
||||
|
||||
Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. [Docker Hub](https://hub.docker.com) is the most popular public registry. Many organizations also setup private Docker registries. Docker is primarily used to manage containers on individual nodes.
|
||||
> 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.
|
||||
|
||||
>**Note:** Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes.
|
||||
# Features of the Rancher API Server
|
||||
|
||||
## Kubernetes
|
||||
The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:
|
||||
|
||||
Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management.
|
||||
- **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.
|
||||
|
||||
A Kubernetes cluster consists of multiple nodes.
|
||||
# Rancher Server Architecture
|
||||
|
||||
- **etcd database**
|
||||
The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment.
|
||||
|
||||
Although you can run etcd on just one node, it typically takes 3, 5 or more nodes to create a High Availability (HA) configuration.
|
||||
The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service).
|
||||
|
||||
- **Master nodes**
|
||||
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.
|
||||
|
||||
Master nodes are stateless and are used to run the API server, scheduler, and controllers.
|
||||
|
||||
- **Worker nodes**
|
||||
|
||||
The application workload runs on worker nodes.
|
||||
|
||||
## Rancher
|
||||
|
||||
The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment.
|
||||
|
||||
The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by Rancher Kubernetes Engine (RKE) and another created by Amazon EKS (Elastic Kubernetes Service).
|
||||
|
||||
|
||||
|
||||
In this section we describe the functionalities of each Rancher server components.
|
||||
|
||||
#### Single Node and High-Availability Installations of Rancher
|
||||
|
||||
|
||||
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.
|
||||
|
||||
In a single-node installation of Rancher, the node running the Rancher server should be separate from your Kubernetes clusters.
|
||||
### Rancher Server Components
|
||||
|
||||
In high-availability installations of Rancher, it is important to note the following:
|
||||
This diagram shows each component that the Rancher server is composed of:
|
||||
|
||||
- The Rancher server cluster should be separate from user clusters. A user cluster is a Kubernetes cluster that runs your apps and services.
|
||||
- The Rancher server cluster and user clusters have separate requirements for hardware and networking. The requirements for the Rancher server can be found [here]({{<baseurl>}}/rancher/v2.x/en/installation/requirements) and the requirements for user clusters can be found [here.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/requirements})
|
||||
- We recommend installing Rancher on a Kubernetes cluster in which each node has all three Kubernetes roles: etcd, controlplane, and worker. However, when you set up the clusters that run your apps and services, we recommend that each node in the cluster should have a single role for stability and scalability. 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)
|
||||
|
||||
|
||||
|
||||
The GitHub repositories for each component of Rancher can be found at the following links:
|
||||
|
||||
#### Rancher API Server
|
||||
|
||||
Rancher API server is built on top of an embedded Kubernetes API server and etcd database. It implements the following functionalities:
|
||||
|
||||
- **User Management**
|
||||
|
||||
Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub.
|
||||
|
||||
- **Authorization**
|
||||
|
||||
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**
|
||||
|
||||
Rancher API server tracks identities of all the nodes in all clusters.
|
||||
|
||||
#### Cluster Controller and Agents
|
||||
|
||||
The cluster controller and cluster agents implement the business logic required to manage Kubernetes clusters.
|
||||
|
||||
- The _cluster controller_ implements the logic required for the global Rancher install. It performs the following actions:
|
||||
|
||||
- Configuration of access control policies to clusters and projects.
|
||||
|
||||
- Provisioning of clusters by calling:
|
||||
|
||||
- The required Docker machine drivers.
|
||||
- Kubernetes engines like RKE and GKE.
|
||||
|
||||
|
||||
- A separate _cluster agent_ instance implements the logic required for the corresponding cluster. It performs the following activities:
|
||||
|
||||
- Workload Management, such as pod creation and deployment within each cluster.
|
||||
|
||||
- Application of the roles and bindings defined in each cluster's global policies.
|
||||
|
||||
- Communication between clusters and Rancher Server: events, stats, node info, and health.
|
||||
|
||||
#### 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.
|
||||
- [Main Rancher server repository](https://github.com/rancher/rancher)
|
||||
- [Rancher UI](https://github.com/rancher/ui)
|
||||
- [Rancher API UI](https://github.com/rancher/api-ui)
|
||||
- [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)
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Kubernetes Concepts
|
||||
weight: 4
|
||||
---
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [About Docker](#about-docker)
|
||||
- [About Kubernetes](#about-kubernetes)
|
||||
- [What is a Kubernetes Cluster?](#what-is-a-kubernetes-cluster)
|
||||
- [Roles for Nodes in Kubernetes Clusters](#roles-for-nodes-in-kubernetes-clusters)
|
||||
- [etcd Nodes](#etcd-nodes)
|
||||
- [Controlplane Nodes](#controlplane-nodes)
|
||||
- [Worker Nodes](#worker-nodes)
|
||||
- [About Helm](#about-helm)
|
||||
|
||||
# About Docker
|
||||
|
||||
Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. [Docker Hub](https://hub.docker.com) is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes.
|
||||
|
||||
>**Note:** Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes.
|
||||
|
||||
# About Kubernetes
|
||||
|
||||
Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management.
|
||||
|
||||
# What is a Kubernetes Cluster?
|
||||
|
||||
A cluster is a group of computers that work together as a single system.
|
||||
|
||||
A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations.
|
||||
|
||||
# Roles for Nodes in Kubernetes Clusters
|
||||
|
||||
Each computing resource in a Kubernetes cluster is called a _node_. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes.
|
||||
|
||||
A Kubernetes cluster consists of at least one etcd, controlplane, and worker node.
|
||||
|
||||
### etcd Nodes
|
||||
|
||||
Rancher uses etcd as a data store in both single node and high-availability installations. In Kubernetes, etcd is also a role for nodes that store the cluster state.
|
||||
|
||||
The state of a Kubernetes cluster is maintained in [etcd.](https://kubernetes.io/docs/concepts/overview/components/#etcd) The etcd nodes run the etcd database.
|
||||
|
||||
The etcd database component is a distributed key-value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. It is recommended to run etcd on multiple nodes so that there's always a backup available for failover.
|
||||
|
||||
Although you can run etcd on just one node, etcd requires a majority of nodes, a quorum, to agree on updates to the cluster state. The cluster should always contain enough healthy etcd nodes to form a quorum. For a cluster with n members, a quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for a quorum.
|
||||
|
||||
Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters.
|
||||
|
||||
### Controlplane Nodes
|
||||
|
||||
Controlplane nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles.
|
||||
|
||||
### Worker Nodes
|
||||
|
||||
Each [worker node](https://kubernetes.io/docs/concepts/architecture/nodes/) runs the following:
|
||||
|
||||
- **Kubelets:** An agent that monitors the state of the node, ensuring your containers are healthy.
|
||||
- **Workloads:** The containers and pods that hold your apps, as well as other types of deployments.
|
||||
|
||||
Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your [workloads]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/workloads/).
|
||||
|
||||
# About Helm
|
||||
|
||||
For high-availability installations of Rancher, Helm is the tool used to install Rancher on a Kubernetes cluster.
|
||||
|
||||
Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh).
|
||||
|
||||
To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster. Helm installs the `tiller` service on your cluster to manage charts because Helm cannot manipulate Kubernetes resources directly.
|
||||
|
||||
Because Rancher Kubernetes Engine enables role-based access control by default, the `tiller` service needs to be given permission to manipulate Kubernetes resources. Therefore, the high-availability Rancher installation instructions show you how to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so that `tiller` has permission to deploy Rancher on the cluster.
|
||||
|
||||
For more information on service accounts and cluster role binding, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Installation Options
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Rancher can be installed on a single node or a high-availability cluster.
|
||||
|
||||
On a single node, Rancher is installed with Docker and many options are configured with Docker commands.
|
||||
|
||||
On a Kubernetes cluster, Rancher is installed with Helm, and Helm commands are used to pass in configuration options. [Helm]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/concepts/#about-helm) is a Kubernetes package manager.
|
||||
|
||||
The simplest way to install Rancher is on a single node with direct access to the Internet. Other options require more steps:
|
||||
|
||||
- For a high-availability installation, you need to first set up a Kubernetes cluster using the Rancher Kubernetes Engine, then install Rancher on the cluster.
|
||||
- If the installation environment is behind an HTTP proxy or in an air gap environment, additional steps are required to work around the lack of direct access to DockerHub and GitHub.
|
||||
|
||||
Depending on your environment, the result of of the extra steps is the increased security and reliability of Rancher.
|
||||
|
||||
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)
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- With [API auditing to record all transactions]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#api-audit-log)
|
||||
- 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.
|
||||
|
||||
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)
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
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 Provisions Kubernetes Clusters](#how-rancher-provisions-kubernetes-clusters)
|
||||
- [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
|
||||
|
||||
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.
|
||||
|
||||
# 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 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.
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 48 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 48 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 40 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 30 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 29 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 84 KiB |
Reference in New Issue
Block a user