From a146ecbcb149821532d59120deae2761481f55ae Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Wed, 7 Sep 2022 16:52:11 -0400 Subject: [PATCH] Updating files --- .../downstream-cluster-configuration.md | 2 +- .../manage-persistent-storage.md | 13 +- .../monitoring-v2-configuration.md | 12 +- .../other-cloud-providers.md | 10 +- .../other-troubleshooting-tips.md | 13 +- .../prometheus-federator-guides.md | 9 +- .../rancher-manager-architecture.md | 185 +----------------- .../rancher-server-configuration.md | 13 +- .../single-node-rancher-in-docker.md | 6 +- ...unicating-with-downstream-user-clusters.md | 133 ++++++++++++- .../rancher-server-and-components.md | 26 ++- .../kubernetes-resources.md | 2 +- .../registered-clusters.md | 2 +- ...-alerts-for-periodic-scan-on-a-schedule.md | 1 - ...reate-a-custom-benchmark-version-to-run.md | 1 - .../cis-scan-guides/delete-a-report.md | 3 +- .../cis-scan-guides/download-a-report.md | 2 +- .../install-rancher-cis-benchmark.md | 1 - .../run-a-scan-periodically-on-a-schedule.md | 1 - .../schedule-recurring-scans.md | 2 +- .../cis-scan-guides/set-alerts.md | 4 +- .../uninstall-rancher-cis-benchmark.md | 1 - .../cis-scan-guides/view-reports.md | 1 - .../downstream-cluster-configuration.md | 2 +- .../manage-persistent-storage.md | 13 +- .../other-cloud-providers.md | 11 +- .../other-troubleshooting-tips.md | 11 +- .../rancher-manager-architecture.md | 171 +--------------- .../rancher-server-configuration.md | 7 +- .../pages-for-subheaders/rke-add-on.md | 7 +- .../single-node-rancher-in-docker.md | 6 +- ...unicating-with-downstream-user-clusters.md | 133 ++++++++++++- .../rancher-server-and-components.md | 26 ++- .../downstream-cluster-configuration.md | 2 +- .../manage-persistent-storage.md | 13 +- .../monitoring-v2-configuration.md | 12 +- .../other-cloud-providers.md | 10 +- .../other-troubleshooting-tips.md | 11 +- .../rancher-manager-architecture.md | 171 +--------------- .../rancher-server-configuration.md | 11 +- .../single-node-rancher-in-docker.md | 6 +- ...unicating-with-downstream-user-clusters.md | 133 ++++++++++++- .../rancher-server-and-components.md | 26 ++- 43 files changed, 666 insertions(+), 559 deletions(-) delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md delete mode 100644 versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md diff --git a/docs/pages-for-subheaders/downstream-cluster-configuration.md b/docs/pages-for-subheaders/downstream-cluster-configuration.md index 2d15adaa3b8..e9065f1fb08 100644 --- a/docs/pages-for-subheaders/downstream-cluster-configuration.md +++ b/docs/pages-for-subheaders/downstream-cluster-configuration.md @@ -2,4 +2,4 @@ title: Downstream Cluster Configuration --- -Users can easily configure downstream clusters with Rancher. The following docs will discuss [node template configuration](./node-template-configuration.md) and [machine configuration](./machine-configuration.md). \ No newline at end of file +The following docs will discuss [node template configuration](./node-template-configuration.md) and [machine configuration](./machine-configuration.md). \ No newline at end of file diff --git a/docs/pages-for-subheaders/manage-persistent-storage.md b/docs/pages-for-subheaders/manage-persistent-storage.md index fa42a3bae89..38f9b23fe1c 100644 --- a/docs/pages-for-subheaders/manage-persistent-storage.md +++ b/docs/pages-for-subheaders/manage-persistent-storage.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Manage Persistent Storage +--- + +The following sections will explain how to manage persistent storage: + +- [How Persistent Storage Works](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md) +- [Set Up Existing Storage](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md) +- [Dynamically Provision New Storage in Rancher](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md) +- [Use an External Ceph Driver](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md) +- [GlusterFS Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md) +- [iSCSI Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/monitoring-v2-configuration.md b/docs/pages-for-subheaders/monitoring-v2-configuration.md index fa42a3bae89..abf493b4487 100644 --- a/docs/pages-for-subheaders/monitoring-v2-configuration.md +++ b/docs/pages-for-subheaders/monitoring-v2-configuration.md @@ -1 +1,11 @@ - \ No newline at end of file +--- +title: Monitoring V2 Configuration +--- + +The following sections will explain important options essential to configuring Monitoring V2 in Rancher: + +- [Receiver Configuration](../reference-guides/monitoring-v2-configuration/receivers.md) +- [Route Configuration](../reference-guides/monitoring-v2-configuration/routes.md) +- [ServiceMonitor and PodMonitor Configuration](../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) +- [Helm Chart Options](../reference-guides/monitoring-v2-configuration/helm-chart-options.md) +- [Examples](../reference-guides/monitoring-v2-configuration/examples.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/other-cloud-providers.md b/docs/pages-for-subheaders/other-cloud-providers.md index fa42a3bae89..b9d8965a762 100644 --- a/docs/pages-for-subheaders/other-cloud-providers.md +++ b/docs/pages-for-subheaders/other-cloud-providers.md @@ -1 +1,9 @@ - \ No newline at end of file +--- +title: Other Cloud Providers +--- + +The following sections will outline how to set up the following cloud providers: + +- [Amazon Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.md) +- [Azure Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.md) +- [Google Compute Cloud Engine Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/other-troubleshooting-tips.md b/docs/pages-for-subheaders/other-troubleshooting-tips.md index fa42a3bae89..75ff99c90b2 100644 --- a/docs/pages-for-subheaders/other-troubleshooting-tips.md +++ b/docs/pages-for-subheaders/other-troubleshooting-tips.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Other Troubleshooting Tips +--- + +- [Kubernetes Resources](../troubleshooting/other-troubleshooting-tips/kubernetes-resources.md) +- [Networking](../troubleshooting/other-troubleshooting-tips/networking.md) +- [DNS](../troubleshooting/other-troubleshooting-tips/dns.md) +- [Rancher HA](../troubleshooting/other-troubleshooting-tips/rancher-ha.md) +- [Registered Clusters](../troubleshooting/other-troubleshooting-tips/registered-clusters.md) +- [Logging](../troubleshooting/other-troubleshooting-tips/logging.md) +- [User ID Tracking in Audit Logs](../troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.md) +- [Expired Webhook Certificate Rotation](../troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/prometheus-federator-guides.md b/docs/pages-for-subheaders/prometheus-federator-guides.md index fa42a3bae89..0f82f71e1ad 100644 --- a/docs/pages-for-subheaders/prometheus-federator-guides.md +++ b/docs/pages-for-subheaders/prometheus-federator-guides.md @@ -1 +1,8 @@ - \ No newline at end of file +--- +title: Prometheus Federator Guides +--- + +- [Enable Prometheus Operator](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md) +- [Uninstall Prometheus Operator](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md) +- [Customize Grafana Dashboards](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md) +- [Set Up Workloads](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/rancher-manager-architecture.md b/docs/pages-for-subheaders/rancher-manager-architecture.md index dcc38870cf7..252d08a512f 100644 --- a/docs/pages-for-subheaders/rancher-manager-architecture.md +++ b/docs/pages-for-subheaders/rancher-manager-architecture.md @@ -3,7 +3,7 @@ title: Architecture weight: 1 --- -This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. +This section focuses on the [Rancher server and its components](../reference-guides/rancher-manager-architecture/rancher-server-and-components.md) and how [Rancher communicates with downstream Kubernetes clusters](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md). For information on the different ways that Rancher can be installed, refer to the [overview of installation options.](installation-and-upgrade.md#overview-of-installation-options) @@ -15,185 +15,4 @@ For guidance about setting up the underlying infrastructure for the Rancher serv This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../reference-guides/kubernetes-concepts.md) page. -::: - -This section covers the following topics: - -- [Rancher server architecture](#rancher-server-architecture) -- [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 (ACE)](#4-authorized-cluster-endpoint-ace) -- [Important files](#important-files) -- [Tools for provisioning Kubernetes clusters](#tools-for-provisioning-kubernetes-clusters) -- [Rancher server components and source code](#rancher-server-components-and-source-code) - -# Rancher Server Architecture - -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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). - -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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. - -The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: - -
Managing Kubernetes Clusters through Rancher's Authentication Proxy
- -![Architecture](/img/rancher-architecture-rancher-api-server.svg) - -You can install Rancher on a single node, or on a high-availability Kubernetes cluster. - -A high-availability Kubernetes installation is recommended for production. - -A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version. - -The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). - -The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. - -# Communicating with Downstream User Clusters - -This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. - -The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. - -
Communicating with Downstream Clusters
- -![Rancher Components](/img/rancher-architecture-cluster-controller.svg) - -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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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_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. Each cluster controller: - -- Watches for resource changes in the downstream cluster -- Brings the current state of the downstream cluster to the desired state -- 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 - -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 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 (ACE) - -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. - -:::note - -- The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE](launch-kubernetes-with-rancher.md) to provision the cluster. The ACE is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS. - -- The [ACE is available for registered RKE2 and K3s clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#authorized-cluster-endpoint-support-for-rke2-and-k3s-clusters) as of Rancher v2.6.3. - -::: - -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. - -:::note Example scenario: - -Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) - -# 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_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. - -:::note - -The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. - -::: - -For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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) - -### Registered 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. - -# Rancher Server Components and Source Code - -This diagram shows each component that the Rancher server is composed of: - -![Rancher Components](/img/rancher-architecture-rancher-components.svg) - -The GitHub repositories for Rancher can be found at the following links: - -- [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) - -This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. +::: \ No newline at end of file diff --git a/docs/pages-for-subheaders/rancher-server-configuration.md b/docs/pages-for-subheaders/rancher-server-configuration.md index fa42a3bae89..0892fb94db3 100644 --- a/docs/pages-for-subheaders/rancher-server-configuration.md +++ b/docs/pages-for-subheaders/rancher-server-configuration.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Rancher Server Configuration +--- + +- [RKE1 Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) +- [RKE2 Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) +- [K3s Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) +- [EKS Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md) +- [AKS Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md) +- [GKE Cluster Configuration](../pages-for-subheaders/gke-cluster-configuration.md) +- [Use Existing Nodes](../pages-for-subheaders/use-existing-nodes.md) +- [Sync Clusters](../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md) \ No newline at end of file diff --git a/docs/pages-for-subheaders/single-node-rancher-in-docker.md b/docs/pages-for-subheaders/single-node-rancher-in-docker.md index fa42a3bae89..61cd166a90c 100644 --- a/docs/pages-for-subheaders/single-node-rancher-in-docker.md +++ b/docs/pages-for-subheaders/single-node-rancher-in-docker.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +title: Single Node Rancher in Docker +--- + +The following docs will discuss [HTTP proxy configuration](../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) and [advanced options](../reference-guides/single-node-rancher-in-docker/advanced-options.md) for Docker installs. \ No newline at end of file diff --git a/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md index fa42a3bae89..e5c41d4e2b2 100644 --- a/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md +++ b/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -1 +1,132 @@ - \ No newline at end of file +--- +title: Communicating with Downstream User Clusters +--- + +This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. + +The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. + +
Communicating with Downstream Clusters
+ +![Rancher Components](/img/rancher-architecture-cluster-controller.svg) + +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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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. Each cluster controller: + +- Watches for resource changes in the downstream cluster +- Brings the current state of the downstream cluster to the desired state +- 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 + +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 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](launch-kubernetes-with-rancher.md) 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 Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) + +# 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. + +> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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. + +# Rancher Server Components and Source Code + +This diagram shows each component that the Rancher server is composed of: + +![Rancher Components](/img/rancher-architecture-rancher-components.svg) + +The GitHub repositories for Rancher can be found at the following links: + +- [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) + +This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. \ No newline at end of file diff --git a/docs/reference-guides/rancher-manager-architecture/rancher-server-and-components.md b/docs/reference-guides/rancher-manager-architecture/rancher-server-and-components.md index fa42a3bae89..d77a513a20d 100644 --- a/docs/reference-guides/rancher-manager-architecture/rancher-server-and-components.md +++ b/docs/reference-guides/rancher-manager-architecture/rancher-server-and-components.md @@ -1 +1,25 @@ - \ No newline at end of file +--- +title: Rancher Server and Components +--- + +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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). + +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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. + +The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: + +
Managing Kubernetes Clusters through Rancher's Authentication Proxy
+ +![Architecture](/img/rancher-architecture-rancher-api-server.svg) + +You can install Rancher on a single node, or on a high-availability Kubernetes cluster. + +A high-availability Kubernetes installation is recommended for production. + +A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version. + +The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). + +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. \ No newline at end of file diff --git a/docs/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md b/docs/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md index b135139882e..624208a6238 100644 --- a/docs/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md +++ b/docs/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md @@ -1,5 +1,5 @@ --- -title: Kubernetes resources +title: Kubernetes Resources weight: 101 --- diff --git a/docs/troubleshooting/other-troubleshooting-tips/registered-clusters.md b/docs/troubleshooting/other-troubleshooting-tips/registered-clusters.md index c40978b36f5..6b5e453402c 100644 --- a/docs/troubleshooting/other-troubleshooting-tips/registered-clusters.md +++ b/docs/troubleshooting/other-troubleshooting-tips/registered-clusters.md @@ -1,5 +1,5 @@ --- -title: Registered clusters +title: Registered Clusters weight: 105 --- diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md index 5b2a91a5adf..b65f65ef4ff 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md @@ -4,5 +4,4 @@ title: Delete a Report 1. From the cluster view in Rancher, click **Tools > CIS Scans.** 1. Go to the report that should be deleted. -1. Click the **⋮ > Delete.** -1. Click **Delete.** \ No newline at end of file +1. Click **⋮ > Delete.** \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md index 9eb4990aa1d..458a7edc7ab 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md @@ -3,6 +3,6 @@ title: Download a Report --- 1. From the cluster view in Rancher, click **Tools > CIS Scans.** -1. Go to the report that you want to download. Click **⋮ > Download.** +1. Go to the report that you want to download. Click **⋮ > Download.** **Result:** The report is downloaded in CSV format. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/schedule-recurring-scans.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/schedule-recurring-scans.md index 65cd538feee..94f75fd1126 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/schedule-recurring-scans.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/schedule-recurring-scans.md @@ -10,7 +10,7 @@ To schedule scans for an existing cluster: 1. Go to the cluster view in Rancher. 1. Click **Tools > CIS Scans.** -1. Click **Add Schedule.** This takes you to the section of the cluster editing page that is applicable to configuring a schedule for CIS scans. (This section can also be reached by going to the cluster view, clicking **⋮ > Edit,** and going to the **Advanced Options.**) +1. Click **Add Schedule.** This takes you to the section of the cluster editing page that is applicable to configuring a schedule for CIS scans. (This section can also be reached by going to the cluster view, clicking **⋮ > Edit,** and going to the **Advanced Options.**) 1. In the **CIS Scan Enabled** field, click **Yes.** [defined in a separate ConfigMap](#skip-tests) 1. In the **CIS Scan Interval (cron)** job, enter a [cron expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) to define how often the cluster will be scanned. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/set-alerts.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/set-alerts.md index a0491535124..56412c91806 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/set-alerts.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/set-alerts.md @@ -19,8 +19,8 @@ To activate an existing alert for a CIS scan result, 1. From the cluster view in Rancher, click **Tools > Alerts.** 1. Go to the section called **A set of alerts for cluster scans.** -1. Go to the alert you want to activate and click **⋮ > Activate.** -1. Go to the alert rule group **A set of alerts for cluster scans** and click **⋮ > Edit.** +1. Go to the alert you want to activate and click **⋮ > Activate.** +1. Go to the alert rule group **A set of alerts for cluster scans** and click **⋮ > Edit.** 1. Scroll down to the **Alert** section. In the **To** field, select the notifier that you would like to use for sending alert notifications. 1. Optional: To limit the frequency of the notifications, click on **Show advanced options** and configure the time interval of the alerts. 1. Click **Save.** diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md deleted file mode 100644 index fa42a3bae89..00000000000 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/downstream-cluster-configuration.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/downstream-cluster-configuration.md index 008f92d1778..126f0472164 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/downstream-cluster-configuration.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/downstream-cluster-configuration.md @@ -2,4 +2,4 @@ title: Downstream Cluster Configuration --- -Users can easily configure downstream clusters with Rancher. The following docs will discuss [node template configuration](./node-template-configuration.md). \ No newline at end of file +The following docs will discuss [node template configuration](./node-template-configuration.md). \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/manage-persistent-storage.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/manage-persistent-storage.md index fa42a3bae89..38f9b23fe1c 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/manage-persistent-storage.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/manage-persistent-storage.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Manage Persistent Storage +--- + +The following sections will explain how to manage persistent storage: + +- [How Persistent Storage Works](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md) +- [Set Up Existing Storage](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md) +- [Dynamically Provision New Storage in Rancher](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md) +- [Use an External Ceph Driver](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md) +- [GlusterFS Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md) +- [iSCSI Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-cloud-providers.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-cloud-providers.md index fa42a3bae89..f9c33021ef9 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-cloud-providers.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-cloud-providers.md @@ -1 +1,10 @@ - \ No newline at end of file +--- +title: Other Cloud Providers +--- + +The following sections will outline how to set up the following cloud providers: + +- [Amazon Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.md) +- [Azure Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.md) +- [Google Compute Cloud Engine Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.md) +- [vSphere Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.md) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-troubleshooting-tips.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-troubleshooting-tips.md index fa42a3bae89..b0f96c034b6 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-troubleshooting-tips.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/other-troubleshooting-tips.md @@ -1 +1,10 @@ - \ No newline at end of file +--- +title: Other Troubleshooting Tips +--- + +- [Kubernetes Resources](../troubleshooting/other-troubleshooting-tips/kubernetes-resources.md) +- [Networking](../troubleshooting/other-troubleshooting-tips/networking.md) +- [DNS](../troubleshooting/other-troubleshooting-tips/dns.md) +- [Rancher HA](../troubleshooting/other-troubleshooting-tips/rancher-ha.md) +- [Registered Clusters](../troubleshooting/other-troubleshooting-tips/registered-clusters.md) +- [Logging](../troubleshooting/other-troubleshooting-tips/logging.md) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-manager-architecture.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-manager-architecture.md index 46216f2e10c..252d08a512f 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-manager-architecture.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-manager-architecture.md @@ -3,7 +3,7 @@ title: Architecture weight: 1 --- -This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. +This section focuses on the [Rancher server and its components](../reference-guides/rancher-manager-architecture/rancher-server-and-components.md) and how [Rancher communicates with downstream Kubernetes clusters](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md). For information on the different ways that Rancher can be installed, refer to the [overview of installation options.](installation-and-upgrade.md#overview-of-installation-options) @@ -11,171 +11,8 @@ For a list of main features of the Rancher API server, refer to the [overview se For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.](../reference-guides/rancher-manager-architecture/architecture-recommendations.md) -> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../reference-guides/kubernetes-concepts.md) page. +:::note -This section covers the following topics: +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../reference-guides/kubernetes-concepts.md) page. -- [Rancher server architecture](#rancher-server-architecture) -- [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 components and source code](#rancher-server-components-and-source-code) - -# Rancher Server Architecture - -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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). - -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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. - -The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: - -
Managing Kubernetes Clusters through Rancher's Authentication Proxy
- -![Architecture](/img/rancher-architecture-rancher-api-server.svg) - -You can install Rancher on a single node, or on a high-availability Kubernetes cluster. - -A high-availability Kubernetes installation is recommended for production. - -A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: - -For Rancher v2.0-v2.4, there was no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start. - -The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. - -# Communicating with Downstream User Clusters - -This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. - -The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. - -
Communicating with Downstream Clusters
- -![Rancher Components](/img/rancher-architecture-cluster-controller.svg) - -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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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. Each cluster controller: - -- Watches for resource changes in the downstream cluster -- Brings the current state of the downstream cluster to the desired state -- 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 - -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 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](launch-kubernetes-with-rancher.md) 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 Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) - -# 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. - -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. - -For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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. - -# Rancher Server Components and Source Code - -This diagram shows each component that the Rancher server is composed of: - -![Rancher Components](/img/rancher-architecture-rancher-components.svg) - -The GitHub repositories for Rancher can be found at the following links: - -- [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) - -This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. +::: \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-server-configuration.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-server-configuration.md index fa42a3bae89..c1a7384f881 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-server-configuration.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-server-configuration.md @@ -1 +1,6 @@ - \ No newline at end of file +--- +title: Rancher Server Configuration +--- + +- [RKE1 Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) +- [Use Existing Nodes](../pages-for-subheaders/use-existing-nodes.md) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rke-add-on.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rke-add-on.md index fa42a3bae89..f7e03d80565 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rke-add-on.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rke-add-on.md @@ -1 +1,6 @@ - \ No newline at end of file +--- +title: RKE Add-On Install +--- + +- [Kubernetes Install with External Load Balancer (TCP/Layer 4)](../getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-4-lb.md) +- [Kubernetes Install with External Load Balancer (HTTPS/Layer 7)](../getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-7-lb.md) diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/single-node-rancher-in-docker.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/single-node-rancher-in-docker.md index fa42a3bae89..61cd166a90c 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/single-node-rancher-in-docker.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/single-node-rancher-in-docker.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +title: Single Node Rancher in Docker +--- + +The following docs will discuss [HTTP proxy configuration](../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) and [advanced options](../reference-guides/single-node-rancher-in-docker/advanced-options.md) for Docker installs. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md index fa42a3bae89..e5c41d4e2b2 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -1 +1,132 @@ - \ No newline at end of file +--- +title: Communicating with Downstream User Clusters +--- + +This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. + +The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. + +
Communicating with Downstream Clusters
+ +![Rancher Components](/img/rancher-architecture-cluster-controller.svg) + +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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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. Each cluster controller: + +- Watches for resource changes in the downstream cluster +- Brings the current state of the downstream cluster to the desired state +- 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 + +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 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](launch-kubernetes-with-rancher.md) 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 Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) + +# 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. + +> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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. + +# Rancher Server Components and Source Code + +This diagram shows each component that the Rancher server is composed of: + +![Rancher Components](/img/rancher-architecture-rancher-components.svg) + +The GitHub repositories for Rancher can be found at the following links: + +- [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) + +This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.md b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.md index fa42a3bae89..5ae4ede06b4 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.md @@ -1 +1,25 @@ - \ No newline at end of file +--- +title: Rancher Server and Components +--- + +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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). + +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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. + +The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: + +
Managing Kubernetes Clusters through Rancher's Authentication Proxy
+ +![Architecture](/img/rancher-architecture-rancher-api-server.svg) + +You can install Rancher on a single node, or on a high-availability Kubernetes cluster. + +A high-availability Kubernetes installation is recommended for production. + +A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: + +For Rancher v2.0-v2.4, there was no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start. + +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/downstream-cluster-configuration.md b/versioned_docs/version-2.5/pages-for-subheaders/downstream-cluster-configuration.md index 008f92d1778..126f0472164 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/downstream-cluster-configuration.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/downstream-cluster-configuration.md @@ -2,4 +2,4 @@ title: Downstream Cluster Configuration --- -Users can easily configure downstream clusters with Rancher. The following docs will discuss [node template configuration](./node-template-configuration.md). \ No newline at end of file +The following docs will discuss [node template configuration](./node-template-configuration.md). \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/manage-persistent-storage.md b/versioned_docs/version-2.5/pages-for-subheaders/manage-persistent-storage.md index fa42a3bae89..38f9b23fe1c 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/manage-persistent-storage.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/manage-persistent-storage.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Manage Persistent Storage +--- + +The following sections will explain how to manage persistent storage: + +- [How Persistent Storage Works](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md) +- [Set Up Existing Storage](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md) +- [Dynamically Provision New Storage in Rancher](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md) +- [Use an External Ceph Driver](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md) +- [GlusterFS Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md) +- [iSCSI Volumes](../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration.md b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration.md index fa42a3bae89..abf493b4487 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration.md @@ -1 +1,11 @@ - \ No newline at end of file +--- +title: Monitoring V2 Configuration +--- + +The following sections will explain important options essential to configuring Monitoring V2 in Rancher: + +- [Receiver Configuration](../reference-guides/monitoring-v2-configuration/receivers.md) +- [Route Configuration](../reference-guides/monitoring-v2-configuration/routes.md) +- [ServiceMonitor and PodMonitor Configuration](../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) +- [Helm Chart Options](../reference-guides/monitoring-v2-configuration/helm-chart-options.md) +- [Examples](../reference-guides/monitoring-v2-configuration/examples.md) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/other-cloud-providers.md b/versioned_docs/version-2.5/pages-for-subheaders/other-cloud-providers.md index fa42a3bae89..b9d8965a762 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/other-cloud-providers.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/other-cloud-providers.md @@ -1 +1,9 @@ - \ No newline at end of file +--- +title: Other Cloud Providers +--- + +The following sections will outline how to set up the following cloud providers: + +- [Amazon Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.md) +- [Azure Cloud Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.md) +- [Google Compute Cloud Engine Provider](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.md) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/other-troubleshooting-tips.md b/versioned_docs/version-2.5/pages-for-subheaders/other-troubleshooting-tips.md index fa42a3bae89..b0f96c034b6 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/other-troubleshooting-tips.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/other-troubleshooting-tips.md @@ -1 +1,10 @@ - \ No newline at end of file +--- +title: Other Troubleshooting Tips +--- + +- [Kubernetes Resources](../troubleshooting/other-troubleshooting-tips/kubernetes-resources.md) +- [Networking](../troubleshooting/other-troubleshooting-tips/networking.md) +- [DNS](../troubleshooting/other-troubleshooting-tips/dns.md) +- [Rancher HA](../troubleshooting/other-troubleshooting-tips/rancher-ha.md) +- [Registered Clusters](../troubleshooting/other-troubleshooting-tips/registered-clusters.md) +- [Logging](../troubleshooting/other-troubleshooting-tips/logging.md) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/rancher-manager-architecture.md b/versioned_docs/version-2.5/pages-for-subheaders/rancher-manager-architecture.md index ae04cc5aeaf..7dd24b62c61 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/rancher-manager-architecture.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/rancher-manager-architecture.md @@ -5,7 +5,7 @@ aliases: - /rancher/v2.x/en/overview/architecture/ --- -This section focuses on the Rancher server, its components, and how Rancher communicates with downstream Kubernetes clusters. +This section focuses on the [Rancher server and its components](../reference-guides/rancher-manager-architecture/rancher-server-and-components.md) and how [Rancher communicates with downstream Kubernetes clusters](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md). For information on the different ways that Rancher can be installed, refer to the [overview of installation options.](installation-and-upgrade.md#overview-of-installation-options) @@ -13,171 +13,8 @@ For a list of main features of the Rancher API server, refer to the [overview se For guidance about setting up the underlying infrastructure for the Rancher server, refer to the [architecture recommendations.](../reference-guides/rancher-manager-architecture/architecture-recommendations.md) -> This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../reference-guides/kubernetes-concepts.md) page. +:::note -This section covers the following topics: +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../reference-guides/kubernetes-concepts.md) page. -- [Rancher server architecture](#rancher-server-architecture) -- [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 components and source code](#rancher-server-components-and-source-code) - -# Rancher Server Architecture - -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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). - -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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. - -The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: - -
Managing Kubernetes Clusters through Rancher's Authentication Proxy
- -![Architecture](/img/rancher-architecture-rancher-api-server.svg) - -You can install Rancher on a single node, or on a high-availability Kubernetes cluster. - -A high-availability Kubernetes installation is recommended for production. - -A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: - -The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) - -The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. - -# Communicating with Downstream User Clusters - -This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. - -The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. - -
Communicating with Downstream Clusters
- -![Rancher Components](/img/rancher-architecture-cluster-controller.svg) - -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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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_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. Each cluster controller: - -- Watches for resource changes in the downstream cluster -- Brings the current state of the downstream cluster to the desired state -- 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 - -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 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](launch-kubernetes-with-rancher.md) to provision the cluster. It is not available for registered 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 Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) - -# 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_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. - -> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. - -For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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) - -### Registered 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. - -# Rancher Server Components and Source Code - -This diagram shows each component that the Rancher server is composed of: - -![Rancher Components](/img/rancher-architecture-rancher-components.svg) - -The GitHub repositories for Rancher can be found at the following links: - -- [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) - -This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. +::: diff --git a/versioned_docs/version-2.5/pages-for-subheaders/rancher-server-configuration.md b/versioned_docs/version-2.5/pages-for-subheaders/rancher-server-configuration.md index fa42a3bae89..a8e1a880ea7 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/rancher-server-configuration.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/rancher-server-configuration.md @@ -1 +1,10 @@ - \ No newline at end of file +--- +title: Rancher Server Configuration +--- + +- [RKE1 Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) +- [EKS Cluster Configuration](../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md) +- [GKE Cluster Configuration](../pages-for-subheaders/gke-cluster-configuration.md) +- [Use Existing Nodes](../pages-for-subheaders/use-existing-nodes.md) +- [Sync Clusters](../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md) +- [RancherD Configuration Reference](../reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/single-node-rancher-in-docker.md b/versioned_docs/version-2.5/pages-for-subheaders/single-node-rancher-in-docker.md index fa42a3bae89..61cd166a90c 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/single-node-rancher-in-docker.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/single-node-rancher-in-docker.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +title: Single Node Rancher in Docker +--- + +The following docs will discuss [HTTP proxy configuration](../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) and [advanced options](../reference-guides/single-node-rancher-in-docker/advanced-options.md) for Docker installs. \ No newline at end of file diff --git a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md index fa42a3bae89..0dd40b8fded 100644 --- a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md +++ b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -1 +1,132 @@ - \ No newline at end of file +--- +title: Communicating with Downstream User Clusters +--- + +This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services. + +The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters. + +
Communicating with Downstream Clusters
+ +![Rancher Components](/img/rancher-architecture-cluster-controller.svg) + +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](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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_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. Each cluster controller: + +- Watches for resource changes in the downstream cluster +- Brings the current state of the downstream cluster to the desired state +- 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 + +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 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](launch-kubernetes-with-rancher.md) to provision the cluster. It is not available for registered 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 Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant 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 section on accessing your cluster with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) + +# 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_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. + +> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file. + +For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) 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 Nodes 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) + +### Registered 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. + +# Rancher Server Components and Source Code + +This diagram shows each component that the Rancher server is composed of: + +![Rancher Components](/img/rancher-architecture-rancher-components.svg) + +The GitHub repositories for Rancher can be found at the following links: + +- [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) + +This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on [contributing to Rancher.](../contribute-to-rancher.md#repositories) To see all libraries and projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. \ No newline at end of file diff --git a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.md b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.md index fa42a3bae89..9a37eb1b165 100644 --- a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.md +++ b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.md @@ -1 +1,25 @@ - \ No newline at end of file +--- +title: Rancher Server and Components +--- + +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 downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service). + +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](kubernetes-clusters-in-rancher-setup.md) for running your workloads. + +The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy: + +
Managing Kubernetes Clusters through Rancher's Authentication Proxy
+ +![Architecture](/img/rancher-architecture-rancher-api-server.svg) + +You can install Rancher on a single node, or on a high-availability Kubernetes cluster. + +A high-availability Kubernetes installation is recommended for production. + +A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: + +The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages. \ No newline at end of file