mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-04-16 11:25:36 +00:00
Merge pull request #15 from jtravee/new-docs-structure
Updating 2.0-2.4, 2.5 with new docs structure
This commit is contained in:
Billy Tat
GitHub
@@ -6,5 +6,5 @@ To get up and running with Rancher quickly, we have included a **Getting Started
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](../docs/pages-for-subheaders/introduction.md), [quick start guides](../docs/pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../docs/pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
Please see the [introduction](./pages-for-subheaders/introduction.md), [quick start guides](./pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](./pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ To get up and running with Rancher quickly, we have included a **Getting Started
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](../docs/pages-for-subheaders/introduction.md), [quick start guides](../docs/pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../docs/pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
Please see the [introduction](../../pages-for-subheaders/introduction.md), [quick start guides](../../pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../../pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
|
||||
## How-to Guides
|
||||
|
||||
@@ -71,7 +71,7 @@ For our new docs, we are working to build up this section as most of our previou
|
||||
|
||||
### Integrations in Rancher
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these [integrations](../../pages-for-subheaders/integrations-in-rancher.md), this subsection has been added under **references**.
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under **Explanations**.
|
||||
|
||||
Examples of some of these integrations are [Harvester](../../explanations/integrations-in-rancher/harvester.md) and [NeuVector](../../explanations/integrations-in-rancher/neuvector.md).
|
||||
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Configure Alerts for Periodic Scan on a Schedule
|
||||
weight: 8
|
||||
---
|
||||
|
||||
It is possible to run a ClusterScan on a schedule.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Create a Custom Benchmark Version for Running a Cluster Scan
|
||||
weight: 9
|
||||
---
|
||||
|
||||
There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Enable Alerting for Rancher CIS Benchmark
|
||||
weight: 7
|
||||
---
|
||||
|
||||
Alerts can be configured to be sent out for a scan that runs on a schedule.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Install Rancher CIS Benchmark
|
||||
weight: 1
|
||||
---
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Run a Scan Periodically on a Schedule
|
||||
weight: 4
|
||||
---
|
||||
|
||||
To run a ClusterScan on a schedule,
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Run a Scan
|
||||
weight: 3
|
||||
---
|
||||
|
||||
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Skip Tests
|
||||
weight: 5
|
||||
---
|
||||
|
||||
CIS scans can be run using test profiles with user-defined skips.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: Uninstall Rancher CIS Benchmark
|
||||
weight: 2
|
||||
---
|
||||
|
||||
1. From the **Cluster Dashboard,** go to the left navigation bar and click **Apps & Marketplace > Installed Apps**.
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
---
|
||||
title: View Reports
|
||||
weight: 6
|
||||
---
|
||||
|
||||
To view the generated CIS scan reports,
|
||||
|
||||
@@ -2,4 +2,4 @@
|
||||
title: Authentication Config
|
||||
---
|
||||
|
||||
In the following tutorials, you will learn how to [manage users and group](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.md), [create local users](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.md), [configure Google OAuth](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md), [configure Active Directory (AD)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md), [configure FreeIPA](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md), [configure Azure AD](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md), [configure GitHub](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md), [configure Keycloak (OIDC)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md), [configure Keycloak (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md), [configure PingIdentity (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md), and how to [configure Okta (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md).
|
||||
In the following tutorials, you will learn how to [manage users and group](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.md), [create local users](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.md), [configure Google OAuth](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md), [configure Active Directory (AD)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md), [configure FreeIPA](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md), [configure Azure AD](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md), [configure GitHub](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md), [configure Keycloak (OIDC)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md), [configure Keycloak (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md), [configure PingIdentity (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md), [configure Okta (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md), [configure Shibboleth (SAML)](../pages-for-subheaders/configure-shibboleth-saml.md), and how to [configure Microsoft AD Federation Service (SAML)](../pages-for-subheaders/configure-microsoft-ad-federation-service-saml.md).
|
||||
@@ -2,113 +2,12 @@
|
||||
title: CIS Scan Guides
|
||||
---
|
||||
|
||||
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark. The CIS scans can run on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE.
|
||||
|
||||
The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench,</a> an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes <a href="https://github.com/vmware-tanzu/sonobuoy" target="_blank">Sonobuoy</a> for report aggregation.
|
||||
|
||||
- [About the CIS Benchmark](#about-the-cis-benchmark)
|
||||
- [About the Generated Report](#about-the-generated-report)
|
||||
- [Test Profiles](#test-profiles)
|
||||
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
|
||||
- [Roles-based Access Control](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md)
|
||||
- [Configuration](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
|
||||
# About the CIS Benchmark
|
||||
|
||||
The Center for Internet Security is a 501(c\)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.
|
||||
|
||||
CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.
|
||||
|
||||
The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is
|
||||
<a href="https://learn.cisecurity.org/benchmarks" target="_blank">here.</a>
|
||||
|
||||
# About the Generated Report
|
||||
|
||||
Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.
|
||||
|
||||
By default, the CIS Benchmark v1.6 is used.
|
||||
|
||||
The Benchmark version is included in the generated report.
|
||||
|
||||
The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.
|
||||
|
||||
Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's [self-assessment guide](./rancher-security.md#the-cis-benchmark-and-self-assessment) for the corresponding Kubernetes version.
|
||||
|
||||
The report contains the following information:
|
||||
|
||||
| Column in Report | Description |
|
||||
|------------------|-------------|
|
||||
| `id` | The ID number of the CIS Benchmark. |
|
||||
| `description` | The description of the CIS Benchmark test. |
|
||||
| `remediation` | What needs to be fixed in order to pass the test. |
|
||||
| `state` | Indicates if the test passed, failed, was skipped, or was not applicable. |
|
||||
| `node_type` | The node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes. |
|
||||
| `audit` | This is the audit check that `kube-bench` runs for this test. |
|
||||
| `audit_config` | Any configuration applicable to the audit script. |
|
||||
| `test_info` | Test-related info as reported by `kube-bench`, if any. |
|
||||
| `commands` | Test-related commands as reported by `kube-bench`, if any. |
|
||||
| `config_commands` | Test-related configuration data as reported by `kube-bench`, if any. |
|
||||
| `actual_value` | The test's actual value, present if reported by `kube-bench`. |
|
||||
| `expected_result` | The test's expected result, present if reported by `kube-bench`. |
|
||||
|
||||
Refer to [the table in the cluster hardening guide](./rancher-security.md) for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.
|
||||
|
||||
# Test Profiles
|
||||
|
||||
The following profiles are available:
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 hardened 1.5
|
||||
- RKE2 permissive 1.6
|
||||
- RKE2 hardened 1.6
|
||||
- AKS
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
You also have the ability to customize a profile by saving a set of tests to skip.
|
||||
|
||||
All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.
|
||||
|
||||
There are two types of RKE cluster scan profiles:
|
||||
|
||||
- **Permissive:** This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
|
||||
- **Hardened:** This profile will not skip any tests, except for the non-applicable tests.
|
||||
|
||||
The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.
|
||||
|
||||
In order to pass the "Hardened" profile, you will need to follow the steps on the [hardening guide](./rancher-security.md#rancher-hardening-guide) and use the `cluster.yml` defined in the hardening guide to provision a hardened cluster.
|
||||
|
||||
The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned:
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.6 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.6 profile is the default.
|
||||
- For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
# About Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to [this page](../explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md).
|
||||
|
||||
For now, only user-defined skipped tests are marked as skipped in the generated report.
|
||||
|
||||
Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.
|
||||
|
||||
# Roles-based Access Control
|
||||
|
||||
For information about permissions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md).
|
||||
|
||||
# Configuration
|
||||
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md).
|
||||
|
||||
_**Tutorials:**_
|
||||
|
||||
Refer to the following tutorials to learn how to [install `rancher-cis-benchmark`](../how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md), [uninstall `rancher-cis-benchmark`](../how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md), [run a scan](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md), [run a scan periodically on a schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md), [skip tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md), [view reports](../how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md), [enable alerting for `rancher-cis-benchmark`](../how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md), [configure alerts for a periodic scan on a schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md), and how to [create a custom benchmark version to run a cluster scan](../how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md).
|
||||
- [Install rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md)
|
||||
- [Uninstall rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md)
|
||||
- [Run a Scan](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md)
|
||||
- [Run a Scan Periodically on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md)
|
||||
- [Skip Tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)
|
||||
- [View Reports](../how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md)
|
||||
- [Enable Alerting for rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md)
|
||||
- [Configure Alerts for Periodic Scan on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md)
|
||||
- [Create a Custom Benchmark Version to Run](../how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md)
|
||||
@@ -11,8 +11,9 @@ The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecuri
|
||||
- [About the Generated Report](#about-the-generated-report)
|
||||
- [Test Profiles](#test-profiles)
|
||||
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
|
||||
- [Roles-based Access Control](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md)
|
||||
- [Configuration](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
- [Roles-based Access Control](#roles-based-access-control)
|
||||
- [Configuration](#configuration)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
|
||||
# About the CIS Benchmark
|
||||
|
||||
@@ -108,4 +109,8 @@ For information about permissions, refer to [this page](../explanations/integrat
|
||||
|
||||
# Configuration
|
||||
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
|
||||
# How-to Guides
|
||||
|
||||
Please refer [here](../pages-for-subheaders/cis-scan-guides.md) for how-to guides on CIS scans.
|
||||
@@ -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).
|
||||
The following docs will discuss [node template configuration](./node-template-configuration.md) and [machine configuration](./machine-configuration.md).
|
||||
@@ -1 +1,72 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Fleet - GitOps at Scale
|
||||
---
|
||||
|
||||
Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It’s also lightweight enough that it works great for a [single cluster](https://fleet.rancher.io/single-cluster-install/) too, but it really shines when you get to a [large scale](https://fleet.rancher.io/multi-cluster-install/). By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.
|
||||
|
||||
Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.
|
||||
|
||||
- [Architecture](#architecture)
|
||||
- [Accessing Fleet in the Rancher UI](#accessing-fleet-in-the-rancher-ui)
|
||||
- [Windows Support](#windows-support)
|
||||
- [GitHub Repository](#github-repository)
|
||||
- [Use Fleet Behind a Proxy](#use-fleet-behind-a-proxy)
|
||||
- [Helm Chart Dependencies](#helm-chart-dependencies)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Documentation](#documentation)
|
||||
|
||||
# Architecture
|
||||
|
||||
For information about how Fleet works, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.md).
|
||||
|
||||
# Accessing Fleet in the Rancher UI
|
||||
|
||||
Fleet comes preinstalled in Rancher and is managed by the **Continuous Delivery** option in the Rancher UI. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer [here](https://fleet.rancher.io/troubleshooting/).
|
||||
|
||||
Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following **gitops** practice.
|
||||
|
||||
Follow the steps below to access Continuous Delivery in the Rancher UI:
|
||||
|
||||
1. Click **☰ > Continous Delivery**.
|
||||
|
||||
1. Select your namespace at the top of the menu, noting the following:
|
||||
|
||||
- By default, **fleet-default** is selected which includes all downstream clusters that are registered through Rancher.
|
||||
|
||||
- You may switch to **fleet-local**, which only contains the **local** cluster, or you may create your own workspace to which you may assign and move clusters.
|
||||
|
||||
- You can then manage clusters by clicking on **Clusters** on the left navigation bar.
|
||||
|
||||
1. Click on **Gitrepos** on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.
|
||||
|
||||
1. Select your [git repository](https://fleet.rancher.io/gitrepo-add/) and [target clusters/cluster group](https://fleet.rancher.io/gitrepo-structure/). You can also create the cluster group in the UI by clicking on **Cluster Groups** from the left navigation bar.
|
||||
|
||||
1. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.
|
||||
|
||||
# Windows Support
|
||||
|
||||
For details on support for clusters with Windows nodes, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md).
|
||||
|
||||
# GitHub Repository
|
||||
|
||||
The Fleet Helm charts are available [here](https://github.com/rancher/fleet/releases/tag/v0.3.10).
|
||||
|
||||
# Using Fleet Behind a Proxy
|
||||
|
||||
For details on using Fleet behind a proxy, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md).
|
||||
|
||||
# Helm Chart Dependencies
|
||||
|
||||
In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run `helm install`, your installation will fail because the dependencies will be missing.
|
||||
|
||||
The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run `helm dependencies update $chart` OR run `helm dependencies build $chart` locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
- **Known Issue**: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the [backup-restore-operator](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place.
|
||||
|
||||
- **Temporary Workaround**: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs [here](https://github.com/rancher/backup-restore-operator#user-flow).
|
||||
|
||||
# Documentation
|
||||
|
||||
The Fleet documentation is at https://fleet.rancher.io/.
|
||||
@@ -1 +1,7 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Integrations in Rancher
|
||||
---
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI.
|
||||
|
||||
Examples of some of these integrations are [Harvester](../explanations/integrations-in-rancher/harvester.md) and [NeuVector](../explanations/integrations-in-rancher/neuvector.md).
|
||||
@@ -2,4 +2,4 @@
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
The [overview](../getting-started/introduction/overview.md) will discuss Rancher's features, capabilities, and how it makes running Kubernetes easy. The guide to the [new Rancher Manager docs structure, Divio,](../getting-started/introduction/what-are-divio-docs?.md) will explain more about the updated look and function of our docs.
|
||||
The [overview](../getting-started/introduction/overview.md) will discuss Rancher's features, capabilities, and how it makes running Kubernetes easy. The guide to the [new Rancher Manager docs structure, Divio,](../getting-started/introduction/what-are-divio-docs.md) will explain more about the updated look and function of our docs.
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Machine Configuration
|
||||
---
|
||||
|
||||
Machine configuration is the arrangement of resources assigned to a virtual machine. Please see the docs for [Amazon EC2](../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2), [DigitalOcean](../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean), and [Azure](../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure) to learn more.
|
||||
@@ -1 +1,12 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Node Template Configuration
|
||||
---
|
||||
|
||||
To learn about node template config, refer to [EC2 Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2), [DigitalOcean Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean), [Azure Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure), [vSphere Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere), and [Nutanix Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix).
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,12 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,8 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -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:
|
||||
|
||||
<figcaption>Managing Kubernetes Clusters through Rancher's Authentication Proxy</figcaption>
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<figcaption>Communicating with Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. [The Authentication Proxy](#1-the-authentication-proxy)
|
||||
2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents)
|
||||
3. [Node Agents](#3-node-agents)
|
||||
4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)
|
||||
|
||||
### 1. The Authentication Proxy
|
||||
|
||||
In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), which provides an identity for processes that run in a pod.
|
||||
|
||||
By default, Rancher generates a [kubeconfig file](../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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
:::
|
||||
@@ -1 +1,12 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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.
|
||||
@@ -33,6 +33,4 @@ This feature enables kubectl to authenticate with the Rancher server and get a n
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server.
|
||||
The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens).
|
||||
Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
@@ -11,7 +11,7 @@ weight: 21
|
||||
- [Project Selection](#project-selection)
|
||||
- [Commands](#commands)
|
||||
- [Rancher CLI Help](#rancher-cli-help)
|
||||
- [Limitations](#limitations)
|
||||
- [Limitations](#limitations)
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
|
||||
@@ -6,6 +6,12 @@ Feature flags were introduced to allow you to try experimental features that are
|
||||
|
||||
To learn about feature values and how to enable features, refer [here](../../pages-for-subheaders/enable-experimental-features.md).
|
||||
|
||||
:::note
|
||||
|
||||
There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.
|
||||
|
||||
:::
|
||||
|
||||
The following is a list of the feature flags available in Rancher:
|
||||
|
||||
- `harvester`: This feature flag is available starting in v2.6.1. It is used to manage access to the Virtualization Management page where users can navigate directly to Harvester clusters and access the Harvester UI. For more information, see [this page](../../explanations/integrations-in-rancher/harvester.md#feature-flag/).
|
||||
|
||||
@@ -1 +1,132 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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.
|
||||
|
||||
<figcaption>Communicating with Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. [The Authentication Proxy](#1-the-authentication-proxy)
|
||||
2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents)
|
||||
3. [Node Agents](#3-node-agents)
|
||||
4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)
|
||||
|
||||
### 1. The Authentication Proxy
|
||||
|
||||
In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) which provides an identity for processes that run in a pod.
|
||||
|
||||
By default, Rancher generates a [kubeconfig file](../../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](../../pages-for-subheaders/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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -1 +1,25 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy:
|
||||
|
||||
<figcaption>Managing Kubernetes Clusters through Rancher's Authentication Proxy</figcaption>
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -2,7 +2,6 @@
|
||||
title: About rancher-selinux
|
||||
---
|
||||
|
||||
|
||||
To allow Rancher to work with SELinux, some functionality has to be manually enabled for the SELinux nodes. To help with that, Rancher provides a SELinux RPM.
|
||||
|
||||
The `rancher-selinux` RPM only contains policies for the [rancher-logging application.](https://github.com/rancher/charts/tree/dev-v2.5/charts/rancher-logging)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Kubernetes resources
|
||||
title: Kubernetes Resources
|
||||
weight: 101
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Registered clusters
|
||||
title: Registered Clusters
|
||||
weight: 105
|
||||
---
|
||||
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Explanations
|
||||
---
|
||||
|
||||
**Explanatory docs** are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
To get up and running with Rancher quickly, we have included a **Getting Started** section.
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](./pages-for-subheaders/introduction.md), [quick start guides](./pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](./pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
@@ -1 +1,112 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: What Are Divio Docs?
|
||||
---
|
||||
|
||||
The [Divio documentation system](https://documentation.divio.com/) is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.
|
||||
|
||||
In our docs, we have used this guideline to craft a unique set of docs which include [getting started](../../getting-started.md), [how-to guides](../../how-to-guides.md) (including [new](../../pages-for-subheaders/new-user-guides.md) and [advanced user guides](../../pages-for-subheaders/advanced-user-guides.md)), [reference guides](../../reference-guides.md), [explanations](../../explanations.md), an [FAQ section](../../faq.md), [troubleshooting tips](../../troubleshooting.md), and the ability to [contribute to Rancher](../../contribute-to-rancher.md).
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
- [New User Guides](#new-user-guides)
|
||||
- [Advanced User Guides](#advanced-user-guides)
|
||||
- [Reference Guides](#reference-guides)
|
||||
- [Explanations](#explanations)
|
||||
- [Integrations in Rancher](#integrations-in-rancher)
|
||||
- [Other Docs Categories](#other-docs-categories)
|
||||
- [FAQ](#faq)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contribute to Rancher](#contribute-to-rancher)
|
||||
- [Overlapping of Categories](#overlapping-of-categories)
|
||||
- [New Structure Goals](#new-structure-goals)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get up and running with Rancher quickly, we have included a **Getting Started** section.
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](../../pages-for-subheaders/introduction.md), [quick start guides](../../pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../../pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
|
||||
## How-to Guides
|
||||
|
||||
How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into [new user guides](#new-user-guides) and [advanced user guides](#advanced-user-guides).
|
||||
|
||||
### New User Guides
|
||||
|
||||
New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".
|
||||
|
||||
The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.
|
||||
|
||||
The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.
|
||||
|
||||
A good example of a new user guide can be found [here](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md).
|
||||
|
||||
### Advanced User Guides
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
|
||||
A good example of an advanced user guide can be found [here](../../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md).
|
||||
|
||||
## Reference Guides
|
||||
|
||||
Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.
|
||||
|
||||
These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.
|
||||
|
||||
The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.
|
||||
|
||||
Good examples of Rancher reference guides would be the [Rancher Manager architecture](../../pages-for-subheaders/rancher-manager-architecture.md) and [cluster configuration guides](../../pages-for-subheaders/cluster-configuration.md).
|
||||
|
||||
## Explanations
|
||||
|
||||
Explanation docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.
|
||||
|
||||
Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.
|
||||
|
||||
For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature [Integrations in Rancher](../../pages-for-subheaders/integrations-in-rancher.md) to discuss our integrated products.
|
||||
|
||||
### Integrations in Rancher
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under **Explanations**.
|
||||
|
||||
Examples of some of these integrations are [Istio](../../pages-for-subheaders/istio.md) and [CIS Scans](../../pages-for-subheaders/cis-scans.md).
|
||||
|
||||
## Other Docs Categories
|
||||
|
||||
### FAQ
|
||||
|
||||
Our [FAQ](../../faq.md) section is designed to answer the questions our users have been most often asking about Rancher v2.x. The nature of these questions may be technical or non-technical.
|
||||
|
||||
We work to continually add to and enhance this section; check back frequently for updates.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
The [troubleshooting section](../../troubleshooting.md) is designed to help both new and existing Rancher users to troubleshoot known issues that they may encounter when using Rancher.
|
||||
|
||||
We work to continually add to and enhance this section; check back frequently for updates.
|
||||
|
||||
### Contribute to Rancher
|
||||
|
||||
The Rancher Manager documentation is always a work-in-progress; the docs work best when being constantly examined, updated, and improved upon. To do this more effectively, we call upon the community to assist us.
|
||||
|
||||
This [contributing to Rancher section](../../contribute-to-rancher.md) will instruct users on the repositories used for Rancher, how to build the repositories, and what information is needed when filing an issue or creating a pull request.
|
||||
|
||||
We review all contributions frequently and will provide feedback to contributors promptly.
|
||||
|
||||
## Overlapping of Categories
|
||||
|
||||
You may have noticed that within the confines of each category - new user guides, advanced user guides, references - there is some overlap. This is true because the flow of information is fluid, and so often docs will include data that could logically fall under more than one category. Although there is the tendency for our docs to overlap somewhat, if we keep in mind the primary functions of each category and work to make those distinct, then the documentation will be much clearer and useful for users.
|
||||
|
||||
## New Structure Goals
|
||||
|
||||
Our previous Rancher documentation focused on individual features and topics; the new Divio paradigm prioritizes function and cohesion.
|
||||
|
||||
Because the previous docs structure was not based on the Divio paradigm, not every doc as it is written currently will fall neatly into a user guide or a reference, for example. Some docs may include elements of several kind of documentation functions.
|
||||
|
||||
As such, we have worked to move our existing documentation into the new paradigm based on each doc's function. Moving forward, we will be creating, rewriting, and reshaping our docs as needed to more closely align with the Divio structure, purpose, and its design concepts.
|
||||
|
||||
Ultimately, the finished product will much more cohesively and effectively assist our users by emphasizing functionality over individual topic or feature-based docs.
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: How-to Guides
|
||||
---
|
||||
|
||||
**How-to guides** serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into [new user guides](./pages-for-subheaders/new-user-guides.md) and [advanced user guides](./pages-for-subheaders/advanced-user-guides.md).
|
||||
@@ -1 +1,42 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Configure Alerts for Periodic Scan on a Schedule
|
||||
---
|
||||
|
||||
Rancher provides a set of alerts for cluster scans. which are not configured to have notifiers by default:
|
||||
|
||||
- A manual cluster scan was completed
|
||||
- A manual cluster scan has failures
|
||||
- A scheduled cluster scan was completed
|
||||
- A scheduled cluster scan has failures
|
||||
|
||||
:::note Prerequisite
|
||||
|
||||
You need to configure a [notifier](../../../explanations/integrations-in-rancher/notifiers.md) before configuring, sending, or receiving alerts.
|
||||
|
||||
:::
|
||||
|
||||
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. 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.**
|
||||
|
||||
**Result:** The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
To create a new alert,
|
||||
|
||||
1. Go to the cluster view and click **Tools > CIS Scans.**
|
||||
1. Click **Add Alert.**
|
||||
1. Fill out the form.
|
||||
1. Enter a name for the alert.
|
||||
1. In the **Is** field, set the alert to be triggered when a scan is completed or when a scan has a failure.
|
||||
1. In the **Send a** field, set the alert as a **Critical,** **Warning,** or **Info** alert level.
|
||||
1. Choose a [notifier](../../../explanations/integrations-in-rancher/notifiers.md) for the alert.
|
||||
|
||||
**Result:** The alert is created and activated. The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
For more information about alerts, refer to [this page.](../../../pages-for-subheaders/cluster-alerts.md)
|
||||
@@ -1 +0,0 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
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 **⋮ > Delete.**
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
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.**
|
||||
|
||||
**Result:** The report is downloaded in CSV format.
|
||||
@@ -1 +0,0 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
@@ -1 +0,0 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
@@ -1 +1,33 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Run a Scan Periodically on a Schedule
|
||||
---
|
||||
|
||||
Recurring scans can be scheduled to run on any RKE Kubernetes cluster.
|
||||
|
||||
To enable recurring scans, edit the advanced options in the cluster configuration during cluster creation or after the cluster has been created.
|
||||
|
||||
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. 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.
|
||||
1. In the **CIS Scan Report Retention** field, enter the number of past reports that should be kept.
|
||||
|
||||
**Result:** The security scan will run and generate reports at the scheduled intervals.
|
||||
|
||||
The test schedule can be configured in the `cluster.yml`:
|
||||
|
||||
```yaml
|
||||
scheduled_cluster_scan:
|
||||
enabled: true
|
||||
scan_config:
|
||||
cis_scan_config:
|
||||
override_benchmark_version: rke-cis-1.4
|
||||
profile: permissive
|
||||
schedule_config:
|
||||
cron_schedule: 0 0 * * *
|
||||
retention: 24
|
||||
```
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Run a Scan
|
||||
---
|
||||
|
||||
# Run a Scan
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > CIS Scans.**
|
||||
1. Click **Run Scan.**
|
||||
1. Choose a CIS scan profile.
|
||||
|
||||
**Result:** A report is generated and displayed in the **CIS Scans** page. To see details of the report, click the report's name.
|
||||
@@ -1 +1,33 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Skip Tests
|
||||
---
|
||||
|
||||
|
||||
You can define a set of tests that will be skipped by the CIS scan when the next report is generated.
|
||||
|
||||
These tests will be skipped for subsequent CIS scans, including both manually triggered and scheduled scans, and the tests will be skipped with any profile.
|
||||
|
||||
The skipped tests will be listed alongside the test profile name in the cluster configuration options when a test profile is selected for a recurring cluster scan. The skipped tests will also be shown every time a scan is triggered manually from the Rancher UI by clicking **Run Scan.** The display of skipped tests allows you to know ahead of time which tests will be run in each scan.
|
||||
|
||||
To skip tests, you will need to define them in a Kubernetes ConfigMap resource. Each skipped CIS scan test is listed in the ConfigMap alongside the version of the CIS benchmark that the test belongs to.
|
||||
|
||||
To skip tests by editing a ConfigMap resource,
|
||||
|
||||
1. Create a `security-scan` namespace.
|
||||
1. Create a ConfigMap named `security-scan-cfg`.
|
||||
1. Enter the skip information under the key `config.json` in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"skip": {
|
||||
"rke-cis-1.4": [
|
||||
"1.1.1",
|
||||
"1.2.2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above, the CIS benchmark version is specified alongside the tests to be skipped for that version.
|
||||
|
||||
**Result:** These tests will be skipped on subsequent scans that use the defined CIS Benchmark version.
|
||||
@@ -1 +0,0 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
@@ -1 +0,0 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
@@ -1 +1,7 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Advanced User Guides
|
||||
---
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
@@ -1 +1,6 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Authentication Config
|
||||
---
|
||||
|
||||
|
||||
In the following tutorials, you will learn how to [manage users and groups](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.md), [create local users](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.md), [configure Google OAuth](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md), [configure Active Directory (AD)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md), [configure OpenLDAP](../pages-for-subheaders/configure-openldap.md), [configure FreeIPA](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md), [configure Azure AD](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md), [configure GitHub](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md), [configure Keycloak](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.md), [configure PingIdentity (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md), [configure Okta (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md), [configure Shibboleth (SAML)](../pages-for-subheaders/configure-shibboleth-saml.md), and how to [configure Microsoft AD Federation Service (SAML)](../pages-for-subheaders/configure-microsoft-ad-federation-service-saml.md).
|
||||
@@ -1 +1,10 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: CIS Scan Guides
|
||||
---
|
||||
|
||||
- [Run a Scan](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md)
|
||||
- [Run a Scan Periodically on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md)
|
||||
- [Skip Tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)
|
||||
- [Configure Alerts for Periodic Scan on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md)
|
||||
- [Delete a Report](../how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md)
|
||||
- [Download a Report](../how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md)
|
||||
@@ -10,13 +10,7 @@ aliases:
|
||||
_Available as of v2.4.0_
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Running a scan](#running-a-scan)
|
||||
- [Scheduling recurring scans](#scheduling-recurring-scans)
|
||||
- [Skipping tests](#skipping-tests)
|
||||
- [Setting alerts](#setting-alerts)
|
||||
- [Deleting a report](#deleting-a-report)
|
||||
- [Downloading a report](#downloading-a-report)
|
||||
- [List of skipped and not applicable tests](#list-of-skipped-and-not-applicable-tests)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
@@ -28,129 +22,6 @@ The security scan cannot run in a cluster that has Windows nodes.
|
||||
|
||||
You will only be able to see the CIS scan reports for clusters that you have access to.
|
||||
|
||||
# Running a Scan
|
||||
# How-to Guides
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > CIS Scans.**
|
||||
1. Click **Run Scan.**
|
||||
1. Choose a CIS scan profile.
|
||||
|
||||
**Result:** A report is generated and displayed in the **CIS Scans** page. To see details of the report, click the report's name.
|
||||
|
||||
# Scheduling Recurring Scans
|
||||
|
||||
Recurring scans can be scheduled to run on any RKE Kubernetes cluster.
|
||||
|
||||
To enable recurring scans, edit the advanced options in the cluster configuration during cluster creation or after the cluster has been created.
|
||||
|
||||
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. In the **CIS Scan Enabled** field, click **Yes.**
|
||||
1. In the **CIS Scan Profile** field, choose a **Permissive** or **Hardened** profile. The corresponding CIS Benchmark version is included in the profile name. Note: Any skipped tests [defined in a separate ConfigMap](#skipping-tests) will be skipped regardless of whether a **Permissive** or **Hardened** profile is selected. When selecting the the permissive profile, you should see which tests were skipped by Rancher (tests that are skipped by default for RKE clusters) and which tests were skipped by a Rancher user. In the hardened test profile, the only skipped tests will be skipped by users.
|
||||
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.
|
||||
1. In the **CIS Scan Report Retention** field, enter the number of past reports that should be kept.
|
||||
|
||||
**Result:** The security scan will run and generate reports at the scheduled intervals.
|
||||
|
||||
The test schedule can be configured in the `cluster.yml`:
|
||||
|
||||
```yaml
|
||||
scheduled_cluster_scan:
|
||||
enabled: true
|
||||
scan_config:
|
||||
cis_scan_config:
|
||||
override_benchmark_version: rke-cis-1.4
|
||||
profile: permissive
|
||||
schedule_config:
|
||||
cron_schedule: 0 0 * * *
|
||||
retention: 24
|
||||
```
|
||||
|
||||
|
||||
# Skipping Tests
|
||||
|
||||
You can define a set of tests that will be skipped by the CIS scan when the next report is generated.
|
||||
|
||||
These tests will be skipped for subsequent CIS scans, including both manually triggered and scheduled scans, and the tests will be skipped with any profile.
|
||||
|
||||
The skipped tests will be listed alongside the test profile name in the cluster configuration options when a test profile is selected for a recurring cluster scan. The skipped tests will also be shown every time a scan is triggered manually from the Rancher UI by clicking **Run Scan.** The display of skipped tests allows you to know ahead of time which tests will be run in each scan.
|
||||
|
||||
To skip tests, you will need to define them in a Kubernetes ConfigMap resource. Each skipped CIS scan test is listed in the ConfigMap alongside the version of the CIS benchmark that the test belongs to.
|
||||
|
||||
To skip tests by editing a ConfigMap resource,
|
||||
|
||||
1. Create a `security-scan` namespace.
|
||||
1. Create a ConfigMap named `security-scan-cfg`.
|
||||
1. Enter the skip information under the key `config.json` in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"skip": {
|
||||
"rke-cis-1.4": [
|
||||
"1.1.1",
|
||||
"1.2.2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above, the CIS benchmark version is specified alongside the tests to be skipped for that version.
|
||||
|
||||
**Result:** These tests will be skipped on subsequent scans that use the defined CIS Benchmark version.
|
||||
|
||||
# Setting Alerts
|
||||
|
||||
Rancher provides a set of alerts for cluster scans. which are not configured to have notifiers by default:
|
||||
|
||||
- A manual cluster scan was completed
|
||||
- A manual cluster scan has failures
|
||||
- A scheduled cluster scan was completed
|
||||
- A scheduled cluster scan has failures
|
||||
|
||||
> **Prerequisite:** You need to configure a [notifier](../explanations/integrations-in-rancher/notifiers.md) before configuring, sending, or receiving alerts.
|
||||
|
||||
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. 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.**
|
||||
|
||||
**Result:** The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
To create a new alert,
|
||||
|
||||
1. Go to the cluster view and click **Tools > CIS Scans.**
|
||||
1. Click **Add Alert.**
|
||||
1. Fill out the form.
|
||||
1. Enter a name for the alert.
|
||||
1. In the **Is** field, set the alert to be triggered when a scan is completed or when a scan has a failure.
|
||||
1. In the **Send a** field, set the alert as a **Critical,** **Warning,** or **Info** alert level.
|
||||
1. Choose a [notifier](../explanations/integrations-in-rancher/notifiers.md) for the alert.
|
||||
|
||||
**Result:** The alert is created and activated. The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
For more information about alerts, refer to [this page.](./cluster-alerts.md)
|
||||
|
||||
# Deleting 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.**
|
||||
|
||||
# Downloading 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.**
|
||||
|
||||
**Result:** The report is downloaded in CSV format.
|
||||
|
||||
# List of Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to [this page](../explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md).
|
||||
Please refer [here](../pages-for-subheaders/cis-scan-guides.md) for how-to guides on CIS scans.
|
||||
@@ -1,83 +1,5 @@
|
||||
---
|
||||
title: Using the Rancher Command Line Interface
|
||||
description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI
|
||||
metaTitle: "Using the Rancher Command Line Interface "
|
||||
metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI"
|
||||
weight: 21
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/cluster-access/cli
|
||||
- /rancher/v2.x/en/cli/
|
||||
title: CLI with Rancher
|
||||
---
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
### Download Rancher CLI
|
||||
|
||||
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary.
|
||||
|
||||
### Requirements
|
||||
|
||||
After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:
|
||||
|
||||
- Your Rancher Server URL, which is used to connect to Rancher Server.
|
||||
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key](../reference-guides/user-settings/api-keys.md).
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `<BEARER_TOKEN>` and `<SERVER_URL>` with your information):
|
||||
|
||||
```bash
|
||||
$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>
|
||||
```
|
||||
|
||||
If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.
|
||||
|
||||
### Project Selection
|
||||
|
||||
Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
|
||||
|
||||
**Example: `./rancher context switch` Output**
|
||||
```
|
||||
User:rancher-cli-directory user$ ./rancher context switch
|
||||
NUMBER CLUSTER NAME PROJECT ID PROJECT NAME
|
||||
1 cluster-2 c-7q96s:p-h4tmb project-2
|
||||
2 cluster-2 c-7q96s:project-j6z6d Default
|
||||
3 cluster-1 c-lchzv:p-xbpdt project-1
|
||||
4 cluster-1 c-lchzv:project-s2mch Default
|
||||
Select a Project:
|
||||
```
|
||||
|
||||
After you enter a number, the console displays a message that you've changed projects.
|
||||
|
||||
```
|
||||
INFO[0005] Setting new context to project project-1
|
||||
INFO[0005] Saving config to /Users/markbishop/.rancher/cli2.json
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
The following commands are available for use in Rancher CLI.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `apps, [app]` | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or Rancher charts. |
|
||||
| `catalog` | Performs operations on [catalogs](./helm-charts-in-rancher.md). |
|
||||
| `clusters, [cluster]` | Performs operations on your [clusters](kubernetes-clusters-in-rancher-setup.md). |
|
||||
| `context` | Switches between Rancher [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). For an example, see [Project Selection](#project-selection). |
|
||||
| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) and [workloads](workloads-and-pods.md)). Specify resources by name or ID. |
|
||||
| `kubectl` |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). |
|
||||
| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). |
|
||||
| `namespaces, [namespace]` |Performs operations on namespaces. |
|
||||
| `nodes, [node]` |Performs operations on nodes. |
|
||||
| `projects, [project]` | Performs operations on [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). |
|
||||
| `ps` | Displays [workloads](workloads-and-pods.md) in a project. |
|
||||
| `settings, [setting]` | Shows the current settings for your Rancher Server. |
|
||||
| `ssh` | Connects to one of your cluster nodes using the SSH protocol. |
|
||||
| `help, [h]` | Shows a list of commands or help for one command. |
|
||||
|
||||
|
||||
### Rancher CLI Help
|
||||
|
||||
Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands.
|
||||
|
||||
All commands accept the `--help` flag, which documents each command's usage.
|
||||
Interact with Rancher using command line interface (CLI) tools from your workstation. The following docs will describe the [Rancher CLI](../reference-guides/cli-with-rancher/rancher-cli.md) and [kubectl Utility](../reference-guides/cli-with-rancher/kubectl-utility).
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Downstream Cluster Configuration
|
||||
---
|
||||
|
||||
The following docs will discuss [node template configuration](./node-template-configuration.md).
|
||||
@@ -26,26 +26,7 @@ If no value has been set, Rancher uses the default value.
|
||||
|
||||
Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.
|
||||
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect.
|
||||
|
||||
> **Note:** As of v2.4.0, there are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.
|
||||
|
||||
The following is a list of the feature flags available in Rancher:
|
||||
|
||||
- `dashboard`: This feature enables the new experimental UI that has a new look and feel. The dashboard also leverages a new API in Rancher which allows the UI to access the default Kubernetes resources without any intervention from Rancher.
|
||||
- `istio-virtual-service-ui`: This feature enables a [UI to create, read, update, and delete Istio virtual services and destination rules](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md), which are traffic management features of Istio.
|
||||
- `proxy`: This feature enables Rancher to use a new simplified code base for the proxy, which can help enhance performance and security. The proxy feature is known to have issues with Helm deployments, which prevents any catalog applications to be deployed which includes Rancher's tools like monitoring, logging, Istio, etc.
|
||||
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.md) In other words, it enables types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
The below table shows the availability and default value for feature flags in Rancher:
|
||||
|
||||
| Feature Flag Name | Default Value | Status | Available as of | Rancher Restart Required? |
|
||||
| ----------------------------- | ------------- | ------------ | --------------- |---|
|
||||
| `dashboard` | `true` | Experimental | v2.4.0 | x |
|
||||
| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | |
|
||||
| `istio-virtual-service-ui` | `true` | GA | v2.3.2 | |
|
||||
| `proxy` | `false` | Experimental | v2.4.0 | |
|
||||
| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | |
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../reference-guides/installation-references/feature-flags.md) for more information.
|
||||
|
||||
# Enabling Features when Starting Rancher
|
||||
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Installation References
|
||||
---
|
||||
|
||||
Please see the following reference guides for other installation resources: [Rancher Helm chart options](../reference-guides/installation-references/helm-chart-options.md), [TLS settings](../reference-guides/installation-references/tls-settings.md), and [feature flags](../reference-guides/installation-references/feature-flags.md).
|
||||
@@ -1 +1,7 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Integrations in Rancher
|
||||
---
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI.
|
||||
|
||||
Examples of some of these integrations are [Istio](../pages-for-subheaders/istio.md) and [CIS Scans](../pages-for-subheaders/cis-scans.md).
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
The [overview](../getting-started/introduction/overview.md) will discuss Rancher's features, capabilities, and how it makes running Kubernetes easy. The guide to the [new Rancher Manager docs structure, Divio,](../getting-started/introduction/what-are-divio-docs.md) will explain more about the updated look and function of our docs.
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
- [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)
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: New User Guides
|
||||
---
|
||||
|
||||
New user guides, also known as **tutorials**, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".
|
||||
|
||||
The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.
|
||||
|
||||
The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Node Template Configuration
|
||||
---
|
||||
|
||||
To learn about node template config, refer to [EC2 Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2), [DigitalOcean Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean), [Azure Node Template Configuration](../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure), and [vSphere Node Template Configuration](../pages-for-subheaders/creating-a-vsphere-cluster.md).
|
||||
@@ -1 +1,10 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,10 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -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:
|
||||
|
||||
<figcaption>Managing Kubernetes Clusters through Rancher's Authentication Proxy</figcaption>
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<figcaption>Communicating with Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. [The Authentication Proxy](#1-the-authentication-proxy)
|
||||
2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents)
|
||||
3. [Node Agents](#3-node-agents)
|
||||
4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)
|
||||
|
||||
### 1. The Authentication Proxy
|
||||
|
||||
In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) which provides an identity for processes that run in a pod.
|
||||
|
||||
By default, Rancher generates a [kubeconfig file](../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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
:::
|
||||
@@ -1 +1,6 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
@@ -1 +1,6 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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)
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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.
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Reference Guides
|
||||
---
|
||||
|
||||
**Reference guides** are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.
|
||||
|
||||
These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.
|
||||
|
||||
The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.
|
||||
|
||||
Good examples of Rancher reference guides would be the [Rancher Manager architecture](./pages-for-subheaders/rancher-manager-architecture.md) and [cluster configuration guides](./pages-for-subheaders/cluster-configuration.md).
|
||||
@@ -1 +1,36 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: kubectl Utility
|
||||
---
|
||||
|
||||
- [kubectl](#kubectl)
|
||||
- [kubectl Utility](#kubectl-utility)
|
||||
- [Authentication with kubectl and kubeconfig Tokens with TTL](#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl)
|
||||
|
||||
# kubectl
|
||||
|
||||
Interact with Rancher using kubectl.
|
||||
|
||||
### kubectl Utility
|
||||
|
||||
Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
|
||||
Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file.
|
||||
|
||||
Run `kubectl cluster-info` or `kubectl get pods` successfully.
|
||||
|
||||
### Authentication with kubectl and kubeconfig Tokens with TTL
|
||||
|
||||
_Requirements_
|
||||
|
||||
If admins have [enforced TTL on kubeconfig tokens](../about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.
|
||||
|
||||
This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:
|
||||
|
||||
1. Local
|
||||
2. Active Directory (LDAP only)
|
||||
3. FreeIPA
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
@@ -1 +1,97 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Rancher CLI
|
||||
description: Interact with Rancher using command line interface (CLI) tools from your workstation.
|
||||
weight: 21
|
||||
---
|
||||
|
||||
- [Rancher CLI](#rancher-cli)
|
||||
- [Download Rancher CLI](#download-rancher-cli)
|
||||
- [Requirements](#requirements)
|
||||
- [CLI Authentication](#cli-authentication)
|
||||
- [Project Selection](#project-selection)
|
||||
- [Commands](#commands)
|
||||
- [Rancher CLI Help](#rancher-cli-help)
|
||||
- [Limitations](#limitations)
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
### Download Rancher CLI
|
||||
|
||||
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/ranchcli/releases) for direct downloads of the binary.
|
||||
|
||||
1. In the upper left corner, click **☰**.
|
||||
1. At the bottom, click **v2.6.x**, where **v2.6.x** is a hyperlinked text indicating the installed Rancher version.
|
||||
1. Under the **CLI Downloads section**, there are links to download the binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/ranchcli/releases) for direct downloads of the binary.
|
||||
|
||||
### Requirements
|
||||
|
||||
After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:
|
||||
|
||||
- Your Rancher Server URL, which is used to connect to Rancher Server.
|
||||
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key](../user-settings/api-keys.md).
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `<BEARER_TOKEN>` and `<SERVER_URL>` with your information):
|
||||
|
||||
```bash
|
||||
$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>
|
||||
```
|
||||
|
||||
If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.
|
||||
|
||||
### Project Selection
|
||||
|
||||
Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project](../../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
|
||||
|
||||
**Example: `./rancher context switch` Output**
|
||||
```
|
||||
User:rancher-cli-directory user$ ./rancher context switch
|
||||
NUMBER CLUSTER NAME PROJECT ID PROJECT NAME
|
||||
1 cluster-2 c-7q96s:p-h4tmb project-2
|
||||
2 cluster-2 c-7q96s:project-j6z6d Default
|
||||
3 cluster-1 c-lchzv:p-xbpdt project-1
|
||||
4 cluster-1 c-lchzv:project-s2mch Default
|
||||
Select a Project:
|
||||
```
|
||||
|
||||
After you enter a number, the console displays a message that you've changed projects.
|
||||
|
||||
```
|
||||
INFO[0005] Setting new context to project project-1
|
||||
INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json
|
||||
```
|
||||
|
||||
Ensure you can run `rancher kubectl get pods` successfully.
|
||||
|
||||
### Commands
|
||||
|
||||
The following commands are available for use in Rancher CLI.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `apps, [app]` | Performs operations on catalog applications (i.e., individual [Helm charts](https://docs.helm.sh/developing_charts/)) or Rancher charts. |
|
||||
| `catalog` | Performs operations on [catalogs](../../pages-for-subheaders/helm-charts-in-rancher.md). |
|
||||
| `clusters, [cluster]` | Performs operations on your [clusters](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md). |
|
||||
| `context` | Switches between Rancher [projects](../../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). For an example, see [Project Selection](#project-selection). |
|
||||
| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects](../../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) and [workloads](../../pages-for-subheaders/workloads-and-pods.md)). Specify resources by name or ID. |
|
||||
| `kubectl` |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). |
|
||||
| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). |
|
||||
| `namespaces, [namespace]` |Performs operations on namespaces. |
|
||||
| `nodes, [node]` |Performs operations on nodes. |
|
||||
| `projects, [project]` | Performs operations on [projects](../../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). |
|
||||
| `ps` | Displays [workloads](../../pages-for-subheaders/workloads-and-pods.md) in a project. |
|
||||
| `settings, [setting]` | Shows the current settings for your Rancher Server. |
|
||||
| `ssh` | Connects to one of your cluster nodes using the SSH protocol. |
|
||||
| `help, [h]` | Shows a list of commands or help for one command. |
|
||||
|
||||
|
||||
### Rancher CLI Help
|
||||
|
||||
Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands.
|
||||
|
||||
All commands accept the `--help` flag, which documents each command's usage.
|
||||
|
||||
### Limitations
|
||||
|
||||
The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../../pages-for-subheaders/helm-charts-in-rancher.md).
|
||||
@@ -1 +1,30 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Feature Flags
|
||||
---
|
||||
|
||||
Feature flags were introduced to allow you to try experimental features that are not enabled by default.
|
||||
|
||||
To learn about feature values and how to enable features, refer [here](../../pages-for-subheaders/enable-experimental-features.md).
|
||||
|
||||
:::note
|
||||
|
||||
As of v2.4.0, there are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.
|
||||
|
||||
:::
|
||||
|
||||
The following is a list of the feature flags available in Rancher:
|
||||
|
||||
- `dashboard`: This feature enables the new experimental UI that has a new look and feel. The dashboard also leverages a new API in Rancher which allows the UI to access the default Kubernetes resources without any intervention from Rancher.
|
||||
- `istio-virtual-service-ui`: This feature enables a [UI to create, read, update, and delete Istio virtual services and destination rules](../../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md), which are traffic management features of Istio.
|
||||
- `proxy`: This feature enables Rancher to use a new simplified code base for the proxy, which can help enhance performance and security. The proxy feature is known to have issues with Helm deployments, which prevents any catalog applications to be deployed which includes Rancher's tools like monitoring, logging, Istio, etc.
|
||||
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.](../../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.md) In other words, it enables types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
The below table shows the availability and default value for feature flags in Rancher:
|
||||
|
||||
| Feature Flag Name | Default Value | Status | Available as of | Rancher Restart Required? |
|
||||
| ----------------------------- | ------------- | ------------ | --------------- |---|
|
||||
| `dashboard` | `true` | Experimental | v2.4.0 | x |
|
||||
| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | |
|
||||
| `istio-virtual-service-ui` | `true` | GA | v2.3.2 | |
|
||||
| `proxy` | `false` | Experimental | v2.4.0 | |
|
||||
| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | |
|
||||
@@ -1 +1,132 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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.
|
||||
|
||||
<figcaption>Communicating with Downstream Clusters</figcaption>
|
||||
|
||||
|
||||
|
||||
The following descriptions correspond to the numbers in the diagram above:
|
||||
|
||||
1. [The Authentication Proxy](#1-the-authentication-proxy)
|
||||
2. [Cluster Controllers and Cluster Agents](#2-cluster-controllers-and-cluster-agents)
|
||||
3. [Node Agents](#3-node-agents)
|
||||
4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)
|
||||
|
||||
### 1. The Authentication Proxy
|
||||
|
||||
In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
|
||||
the pods. Bob is authenticated through Rancher's authentication proxy.
|
||||
|
||||
The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.
|
||||
|
||||
Rancher communicates with Kubernetes clusters using a [service account,](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) which provides an identity for processes that run in a pod.
|
||||
|
||||
By default, Rancher generates a [kubeconfig file](../../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](../../pages-for-subheaders/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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -1 +1,25 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
The diagram below shows how users can manipulate both [Rancher-launched Kubernetes](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) clusters and [hosted Kubernetes](../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md) clusters through Rancher's authentication proxy:
|
||||
|
||||
<figcaption>Managing Kubernetes Clusters through Rancher's Authentication Proxy</figcaption>
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -88,7 +88,7 @@ To enable project network isolation as a cluster option, you will need to use Ca
|
||||
|
||||
### Kubernetes Cloud Providers
|
||||
|
||||
You can configure a [Kubernetes cloud provider](cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage](../../../pages-for-subheaders/create-kubernetes-persistent-storage.md) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider.
|
||||
You can configure a [Kubernetes cloud provider](../../../pages-for-subheaders/set-up-cloud-providers.md). If you want to use [volumes and storage](../../../pages-for-subheaders/create-kubernetes-persistent-storage.md) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider.
|
||||
|
||||
>**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#cluster-config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider.
|
||||
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Explanations
|
||||
---
|
||||
|
||||
**Explanatory docs** are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
To get up and running with Rancher quickly, we have included a **Getting Started** section.
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](./pages-for-subheaders/introduction.md), [quick start guides](./pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](./pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
@@ -38,7 +38,7 @@ The Rancher API server is built on top of an embedded Kubernetes API server and
|
||||
### Working with Kubernetes
|
||||
|
||||
- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) on existing nodes, or perform [Kubernetes upgrades.](../installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)
|
||||
- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts](catalog/) that make it easy to repeatedly deploy applications.
|
||||
- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts](../../pages-for-subheaders/helm-charts-in-rancher.md) that make it easy to repeatedly deploy applications.
|
||||
- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration](../../pages-for-subheaders/manage-projects.md) and for [managing applications within projects.](../../pages-for-subheaders/kubernetes-resources-setup.md)
|
||||
- **Pipelines:** Setting up a [pipeline](../../how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.md) can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects.
|
||||
- **Istio:** Our [integration with Istio](../../pages-for-subheaders/istio.md) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
|
||||
|
||||
@@ -1 +1,112 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: What Are Divio Docs?
|
||||
---
|
||||
|
||||
The [Divio documentation system](https://documentation.divio.com/) is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.
|
||||
|
||||
In our docs, we have used this guideline to craft a unique set of docs which include [getting started](../../getting-started.md), [how-to guides](../../how-to-guides.md) (including [new](../../pages-for-subheaders/new-user-guides.md) and [advanced user guides](../../pages-for-subheaders/advanced-user-guides.md)), [reference guides](../../reference-guides.md), [explanations](../../explanations.md), an [FAQ section](../../faq.md), [troubleshooting tips](../../troubleshooting.md), and the ability to [contribute to Rancher](../../contribute-to-rancher.md).
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
- [New User Guides](#new-user-guides)
|
||||
- [Advanced User Guides](#advanced-user-guides)
|
||||
- [Reference Guides](#reference-guides)
|
||||
- [Explanations](#explanations)
|
||||
- [Integrations in Rancher](#integrations-in-rancher)
|
||||
- [Other Docs Categories](#other-docs-categories)
|
||||
- [FAQ](#faq)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contribute to Rancher](#contribute-to-rancher)
|
||||
- [Overlapping of Categories](#overlapping-of-categories)
|
||||
- [New Structure Goals](#new-structure-goals)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get up and running with Rancher quickly, we have included a **Getting Started** section.
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](../../pages-for-subheaders/introduction.md), [quick start guides](../../pages-for-subheaders/quick-start-guides.md), and the [installation and upgrade](../../pages-for-subheaders/installation-and-upgrade.md) sections for more.
|
||||
|
||||
## How-to Guides
|
||||
|
||||
How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into [new user guides](#new-user-guides) and [advanced user guides](#advanced-user-guides).
|
||||
|
||||
### New User Guides
|
||||
|
||||
New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".
|
||||
|
||||
The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.
|
||||
|
||||
The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.
|
||||
|
||||
A good example of a new user guide can be found [here](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md).
|
||||
|
||||
### Advanced User Guides
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
|
||||
A good example of an advanced user guide can be found [here](../../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md).
|
||||
|
||||
## Reference Guides
|
||||
|
||||
Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.
|
||||
|
||||
These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.
|
||||
|
||||
The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.
|
||||
|
||||
Good examples of Rancher reference guides would be the [Rancher Manager architecture](../../pages-for-subheaders/rancher-manager-architecture.md) and [cluster configuration guides](../../pages-for-subheaders/cluster-configuration.md).
|
||||
|
||||
## Explanations
|
||||
|
||||
Explanation docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.
|
||||
|
||||
Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.
|
||||
|
||||
For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature [Integrations in Rancher](../../pages-for-subheaders/integrations-in-rancher.md) to discuss our integrated products.
|
||||
|
||||
### Integrations in Rancher
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under **Explanations**.
|
||||
|
||||
Examples of some of these integrations are [Fleet - GitOps at Scale](../../pages-for-subheaders/fleet-gitops-at-scale.md) and [Monitoring and Alerting](../../pages-for-subheaders/monitoring-and-alerting.md).
|
||||
|
||||
## Other Docs Categories
|
||||
|
||||
### FAQ
|
||||
|
||||
Our [FAQ](../../faq.md) section is designed to answer the questions our users have been most often asking about Rancher v2.x. The nature of these questions may be technical or non-technical.
|
||||
|
||||
We work to continually add to and enhance this section; check back frequently for updates.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
The [troubleshooting section](../../troubleshooting.md) is designed to help both new and existing Rancher users to troubleshoot known issues that they may encounter when using Rancher.
|
||||
|
||||
We work to continually add to and enhance this section; check back frequently for updates.
|
||||
|
||||
### Contribute to Rancher
|
||||
|
||||
The Rancher Manager documentation is always a work-in-progress; the docs work best when being constantly examined, updated, and improved upon. To do this more effectively, we call upon the community to assist us.
|
||||
|
||||
This [contributing to Rancher section](../../contribute-to-rancher.md) will instruct users on the repositories used for Rancher, how to build the repositories, and what information is needed when filing an issue or creating a pull request.
|
||||
|
||||
We review all contributions frequently and will provide feedback to contributors promptly.
|
||||
|
||||
## Overlapping of Categories
|
||||
|
||||
You may have noticed that within the confines of each category - new user guides, advanced user guides, references - there is some overlap. This is true because the flow of information is fluid, and so often docs will include data that could logically fall under more than one category. Although there is the tendency for our docs to overlap somewhat, if we keep in mind the primary functions of each category and work to make those distinct, then the documentation will be much clearer and useful for users.
|
||||
|
||||
## New Structure Goals
|
||||
|
||||
Our previous Rancher documentation focused on individual features and topics; the new Divio paradigm prioritizes function and cohesion.
|
||||
|
||||
Because the previous docs structure was not based on the Divio paradigm, not every doc as it is written currently will fall neatly into a user guide or a reference, for example. Some docs may include elements of several kind of documentation functions.
|
||||
|
||||
As such, we have worked to move our existing documentation into the new paradigm based on each doc's function. Moving forward, we will be creating, rewriting, and reshaping our docs as needed to more closely align with the Divio structure, purpose, and its design concepts.
|
||||
|
||||
Ultimately, the finished product will much more cohesively and effectively assist our users by emphasizing functionality over individual topic or feature-based docs.
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: How-to Guides
|
||||
---
|
||||
|
||||
**How-to guides** serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into [new user guides](./pages-for-subheaders/new-user-guides.md) and [advanced user guides](./pages-for-subheaders/advanced-user-guides.md).
|
||||
@@ -1 +1,40 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Configure Alerts for Periodic Scan on a Schedule
|
||||
---
|
||||
|
||||
It is possible to run a ClusterScan on a schedule.
|
||||
|
||||
A scheduled scan can also specify if you should receive alerts when the scan completes.
|
||||
|
||||
Alerts are supported only for a scan that runs on a schedule.
|
||||
|
||||
The CIS Benchmark application supports two types of alerts:
|
||||
|
||||
- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
|
||||
- Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state.
|
||||
|
||||
:::note Prerequisite
|
||||
|
||||
Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
|
||||
While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers/#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
:::
|
||||
|
||||
To configure alerts for a scan that runs on a schedule,
|
||||
|
||||
1. Please enable alerts on the `rancher-cis-benchmark` application (#enabling-alerting-for-rancher-cis-benchmark)
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule**.
|
||||
1. Check the boxes next to the Alert types under **Alerting**.
|
||||
1. Optional: Choose a **Retention Count**, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Create a Custom Benchmark Version for Running a Cluster Scan
|
||||
---
|
||||
|
||||
There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
|
||||
|
||||
It is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application.
|
||||
|
||||
For details, see [this page.](../../../explanations/integrations-in-rancher/cis-scans/custom-benchmark.md)
|
||||
@@ -1 +1,19 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Enable Alerting for Rancher CIS Benchmark
|
||||
---
|
||||
|
||||
Alerts can be configured to be sent out for a scan that runs on a schedule.
|
||||
|
||||
:::note Prerequisite:
|
||||
|
||||
Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers/#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
:::
|
||||
|
||||
While installing or upgrading the `rancher-cis-benchmark` Helm chart, set the following flag to `true` in the `values.yaml`:
|
||||
|
||||
```yaml
|
||||
alerts:
|
||||
enabled: true
|
||||
```
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Install Rancher CIS Benchmark
|
||||
---
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to install CIS Benchmark and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps & Marketplace > Charts**.
|
||||
1. Click **CIS Benchmark**
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
|
||||
@@ -1 +1,20 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Run a Scan Periodically on a Schedule
|
||||
---
|
||||
|
||||
To run a ClusterScan on a schedule,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid <a href="https://en.wikipedia.org/wiki/Cron#CRON_expression" target="_blank">cron schedule expression</a> in the field **Schedule**.
|
||||
1. Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. The **Next Scan** value indicates the next time this scan will run again.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
You can also see the previous reports by choosing the report from the **Reports** dropdown on the scan detail page.
|
||||
@@ -1 +1,22 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Run a Scan
|
||||
---
|
||||
|
||||
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
|
||||
|
||||
:::note
|
||||
|
||||
There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
|
||||
|
||||
:::
|
||||
|
||||
To run a scan,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
|
||||
@@ -1 +1,34 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Skip Tests
|
||||
---
|
||||
|
||||
CIS scans can be run using test profiles with user-defined skips.
|
||||
|
||||
To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Profile**.
|
||||
1. From here, you can create a profile in multiple ways. To make a new profile, click **Create** and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile and click **⋮ Clone**. If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the `skipTests` directive. You will also give the profile a name:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScanProfile
|
||||
metadata:
|
||||
annotations:
|
||||
meta.helm.sh/release-name: clusterscan-operator
|
||||
meta.helm.sh/release-namespace: cis-operator-system
|
||||
labels:
|
||||
app.kubernetes.io/managed-by: Helm
|
||||
name: "<example-profile>"
|
||||
spec:
|
||||
benchmarkVersion: cis-1.5
|
||||
skipTests:
|
||||
- "1.1.20"
|
||||
- "1.1.21"
|
||||
```
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A new CIS scan profile is created.
|
||||
|
||||
When you [run a scan](#running-a-scan) that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as `Skip`.
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Uninstall Rancher CIS Benchmark
|
||||
---
|
||||
|
||||
1. From the **Cluster Dashboard,** go to the left navigation bar and click **Apps & Marketplace > Installed Apps**.
|
||||
1. Go to the `cis-operator-system` namespace and check the boxes next to `rancher-cis-benchmark-crd` and `rancher-cis-benchmark`.
|
||||
1. Click **Delete** and confirm **Delete**.
|
||||
|
||||
**Result:** The `rancher-cis-benchmark` application is uninstalled.
|
||||
@@ -1 +1,12 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: View Reports
|
||||
---
|
||||
|
||||
To view the generated CIS scan reports,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
|
||||
|
||||
One can download the report from the Scans list or from the scan detail page.
|
||||
@@ -1 +1,7 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Advanced User Guides
|
||||
---
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Authentication Config
|
||||
---
|
||||
|
||||
In the following tutorials, you will learn how to [manage users and groups](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.md), [create local users](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.md), [configure Google OAuth](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md), [configure Active Directory (AD)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md), [configure OpenLDAP](../pages-for-subheaders/configure-openldap.md), [configure FreeIPA](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md), [configure Azure AD](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md), [configure GitHub](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md), [configure Keycloak](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.md), [configure PingIdentity (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md), [configure Okta (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md), [configure Shibboleth (SAML)](../pages-for-subheaders/configure-shibboleth-saml.md), and how to [configure Microsoft AD Federation Service (SAML)](../pages-for-subheaders/configure-microsoft-ad-federation-service-saml.md).
|
||||
@@ -1,364 +1,13 @@
|
||||
---
|
||||
title: CIS Scans
|
||||
weight: 17
|
||||
aliases:
|
||||
- /rancher/v2.5/en/cis-scans/v2.5
|
||||
- /rancher/v2.x/en/cis-scans/
|
||||
- /rancher/v2.x/en/cis-scans/v2.5/
|
||||
title: CIS Scan Guides
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.
|
||||
|
||||
The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench,</a> an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes <a href="https://github.com/vmware-tanzu/sonobuoy" target="_blank">Sonobuoy</a> for report aggregation.
|
||||
|
||||
- [Changes in Rancher v2.5](#changes-in-rancher-v2-5)
|
||||
- [About the CIS Benchmark](#about-the-cis-benchmark)
|
||||
- [About the Generated Report](#about-the-generated-report)
|
||||
- [Test Profiles](#test-profiles)
|
||||
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
|
||||
- [Roles-based Access Control](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md)
|
||||
- [Configuration](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
|
||||
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
|
||||
- [Running a Scan](#running-a-scan)
|
||||
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
|
||||
- [Skipping Tests](#skipping-tests)
|
||||
- [Viewing Reports](#viewing-reports)
|
||||
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
|
||||
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
|
||||
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
|
||||
|
||||
# Changes in Rancher v2.5
|
||||
|
||||
We now support running CIS scans on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE. Previously it was only supported to run CIS scans on RKE Kubernetes clusters.
|
||||
|
||||
In Rancher v2.4, the CIS scan tool was available from the **cluster manager** in the Rancher UI. Now it is available in the **Cluster Explorer** and it can be enabled and deployed using a Helm chart. It can be installed from the Rancher UI, but it can also be installed independently of Rancher. It deploys a CIS scan operator for the cluster, and deploys Kubernetes custom resources for cluster scans. The custom resources can be managed directly from the **Cluster Explorer.**
|
||||
|
||||
In v1 of the CIS scan tool, which was available in Rancher v2.4 through the cluster manager, recurring scans could be scheduled. The ability to schedule recurring scans is now also available for CIS v2 from Rancher v2.5.4.
|
||||
|
||||
Support for alerting for the cluster scan results is now also available from Rancher v2.5.4.
|
||||
|
||||
In Rancher v2.4, permissive and hardened profiles were included. In Rancher v2.5.0 and in v2.5.4, more profiles were included.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Profiles in v2.5.4">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- EKS
|
||||
- GKE
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 permissive 1.5
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Profiles in v2.5.0-v2.5.3">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- RKE permissive
|
||||
- RKE hardened
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
<br/>
|
||||
|
||||
|
||||
The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned and the Rancher version:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="v2.5.4">
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.6 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.5 profile is the default.
|
||||
- For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="v2.5.0-v2.5.3">
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.5 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE permissive profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For cluster types other than RKE, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> **Note:** CIS v1 cannot run on a cluster when CIS v2 is deployed. In other words, after `rancher-cis-benchmark` is installed, you can't run scans by going to the Cluster Manager view in the Rancher UI and clicking <b>Tools > CIS Scans.</b>
|
||||
|
||||
# About the CIS Benchmark
|
||||
|
||||
The Center for Internet Security is a 501(c\)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.
|
||||
|
||||
CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.
|
||||
|
||||
The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is
|
||||
<a href="https://learn.cisecurity.org/benchmarks" target="_blank">here.</a>
|
||||
|
||||
# About the Generated Report
|
||||
|
||||
Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.
|
||||
|
||||
From Rancher v2.5.4, the scan uses the CIS Benchmark v1.6 by default. In Rancher v2.5.0-2.5.3, the CIS Benchmark v1.5. is used.
|
||||
|
||||
The Benchmark version is included in the generated report.
|
||||
|
||||
The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.
|
||||
|
||||
Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's [self-assessment guide](./rancher-security.md#the-cis-benchmark-and-self-assessment) for the corresponding Kubernetes version.
|
||||
|
||||
The report contains the following information:
|
||||
|
||||
| Column in Report | Description |
|
||||
|------------------|-------------|
|
||||
| `id` | The ID number of the CIS Benchmark. |
|
||||
| `description` | The description of the CIS Benchmark test. |
|
||||
| `remediation` | What needs to be fixed in order to pass the test. |
|
||||
| `state` | Indicates if the test passed, failed, was skipped, or was not applicable. |
|
||||
| `node_type` | The node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes. |
|
||||
| `audit` | This is the audit check that `kube-bench` runs for this test. |
|
||||
| `audit_config` | Any configuration applicable to the audit script. |
|
||||
| `test_info` | Test-related info as reported by `kube-bench`, if any. |
|
||||
| `commands` | Test-related commands as reported by `kube-bench`, if any. |
|
||||
| `config_commands` | Test-related configuration data as reported by `kube-bench`, if any. |
|
||||
| `actual_value` | The test's actual value, present if reported by `kube-bench`. |
|
||||
| `expected_result` | The test's expected result, present if reported by `kube-bench`. |
|
||||
|
||||
Refer to the [table in the cluster hardening guide](./rancher-security.md) for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.
|
||||
|
||||
# Test Profiles
|
||||
|
||||
The following profiles are available:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Profiles in v2.5.4">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- EKS
|
||||
- GKE
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 permissive 1.5
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Profiles in v2.5.0-v2.5.3">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- RKE permissive
|
||||
- RKE hardened
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You also have the ability to customize a profile by saving a set of tests to skip.
|
||||
|
||||
All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.
|
||||
|
||||
There are two types of RKE cluster scan profiles:
|
||||
|
||||
- **Permissive:** This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
|
||||
- **Hardened:** This profile will not skip any tests, except for the non-applicable tests.
|
||||
|
||||
The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.
|
||||
|
||||
In order to pass the "Hardened" profile, you will need to follow the steps on the [hardening guide](./rancher-security.md#rancher-hardening-guide) and use the `cluster.yml` defined in the hardening guide to provision a hardened cluster.
|
||||
|
||||
# About Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to [this page](../explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md).
|
||||
|
||||
For now, only user-defined skipped tests are marked as skipped in the generated report.
|
||||
|
||||
Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.
|
||||
|
||||
# Roles-based Access Control
|
||||
|
||||
For information about permissions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md).
|
||||
|
||||
# Configuration
|
||||
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md).
|
||||
|
||||
# How-to Guides
|
||||
|
||||
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
|
||||
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
|
||||
- [Running a Scan](#running-a-scan)
|
||||
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
|
||||
- [Skipping Tests](#skipping-tests)
|
||||
- [Viewing Reports](#viewing-reports)
|
||||
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
|
||||
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
|
||||
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
|
||||
### Installing rancher-cis-benchmark
|
||||
|
||||
1. In the Rancher UI, go to the **Cluster Explorer.**
|
||||
1. Click **Apps.**
|
||||
1. Click `rancher-cis-benchmark`.
|
||||
1. Click **Install.**
|
||||
|
||||
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
|
||||
|
||||
### Uninstalling rancher-cis-benchmark
|
||||
|
||||
1. From the **Cluster Explorer,** go to the top left dropdown menu and click **Apps & Marketplace.**
|
||||
1. Click **Installed Apps.**
|
||||
1. Go to the `cis-operator-system` namespace and check the boxes next to `rancher-cis-benchmark-crd` and `rancher-cis-benchmark`.
|
||||
1. Click **Delete** and confirm **Delete.**
|
||||
|
||||
**Result:** The `rancher-cis-benchmark` application is uninstalled.
|
||||
|
||||
### Running a Scan
|
||||
|
||||
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
|
||||
|
||||
Note: There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
|
||||
|
||||
To run a scan,
|
||||
|
||||
1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.**
|
||||
1. In the **Scans** section, click **Create.**
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
|
||||
### Running a Scan Periodically on a Schedule
|
||||
_Available as of v2.5.4_
|
||||
|
||||
To run a ClusterScan on a schedule,
|
||||
|
||||
1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.**
|
||||
1. In the **Scans** section, click **Create.**
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule.**
|
||||
1. Enter a valid <a href="https://en.wikipedia.org/wiki/Cron#CRON_expression" target="_blank">cron schedule expression</a> in the field **Schedule.**
|
||||
1. Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. The **Next Scan** value indicates the next time this scan will run again.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
You can also see the previous reports by choosing the report from the **Reports** dropdown on the scan detail page.
|
||||
|
||||
### Skipping Tests
|
||||
|
||||
CIS scans can be run using test profiles with user-defined skips.
|
||||
|
||||
To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.
|
||||
|
||||
1. In the **Cluster Explorer,** go to the top-left dropdown menu and click **CIS Benchmark.**
|
||||
1. Click **Profiles.**
|
||||
1. From here, you can create a profile in multiple ways. To make a new profile, click **Create** and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile, click the three vertical dots, and click **Clone as YAML.** If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the `skipTests` directive. You will also give the profile a name:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScanProfile
|
||||
metadata:
|
||||
annotations:
|
||||
meta.helm.sh/release-name: clusterscan-operator
|
||||
meta.helm.sh/release-namespace: cis-operator-system
|
||||
labels:
|
||||
app.kubernetes.io/managed-by: Helm
|
||||
name: "<example-profile>"
|
||||
spec:
|
||||
benchmarkVersion: cis-1.5
|
||||
skipTests:
|
||||
- "1.1.20"
|
||||
- "1.1.21"
|
||||
```
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** A new CIS scan profile is created.
|
||||
|
||||
When you [run a scan](#running-a-scan) that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as `Skip`.
|
||||
|
||||
### Viewing Reports
|
||||
|
||||
To view the generated CIS scan reports,
|
||||
|
||||
1. In the **Cluster Explorer,** go to the top left dropdown menu and click **Cluster Explorer > CIS Benchmark.**
|
||||
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
|
||||
|
||||
One can download the report from the Scans list or from the scan detail page.
|
||||
|
||||
### Enabling Alerting for rancher-cis-benchmark
|
||||
_Available as of v2.5.4_
|
||||
|
||||
Alerts can be configured to be sent out for a scan that runs on a schedule.
|
||||
|
||||
> **Prerequisite:**
|
||||
>
|
||||
> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../reference-guides/monitoring-v2-configuration/receivers.md)
|
||||
>
|
||||
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.](../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
While installing or upgrading the `rancher-cis-benchmark` application, set the following flag to `true` in the `values.yaml`:
|
||||
|
||||
```yaml
|
||||
alerts:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### Configuring Alerts for a Periodic Scan on a Schedule
|
||||
_Available as of v2.5.4_
|
||||
|
||||
From Rancher v2.5.4, it is possible to run a ClusterScan on a schedule.
|
||||
|
||||
A scheduled scan can also specify if you should receive alerts when the scan completes.
|
||||
|
||||
Alerts are supported only for a scan that runs on a schedule.
|
||||
|
||||
The `rancher-cis-benchmark` application supports two types of alerts:
|
||||
|
||||
- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
|
||||
- Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state.
|
||||
|
||||
> **Prerequisite:**
|
||||
>
|
||||
> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../reference-guides/monitoring-v2-configuration/receivers.md)
|
||||
>
|
||||
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.](../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
To configure alerts for a scan that runs on a schedule,
|
||||
|
||||
1. Please enable alerts on the `rancher-cis-benchmark` application (#enabling-alerting-for-rancher-cis-benchmark)
|
||||
1. Go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > CIS Benchmark.**
|
||||
1. In the **Scans** section, click **Create.**
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule.**
|
||||
1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule.**
|
||||
1. Check the boxes next to the Alert types under **Alerting.**
|
||||
1. Optional: Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
### Creating a Custom Benchmark Version for Running a Cluster Scan
|
||||
_Available as of v2.5.4_
|
||||
|
||||
There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
|
||||
|
||||
It is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application.
|
||||
|
||||
For details, see [this page.](../explanations/integrations-in-rancher/cis-scans/custom-benchmark.md)
|
||||
- [Install rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md)
|
||||
- [Uninstall rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md)
|
||||
- [Run a Scan](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md)
|
||||
- [Run a Scan Periodically on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md)
|
||||
- [Skip Tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)
|
||||
- [View Reports](../how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md)
|
||||
- [Enable Alerting for rancher-cis-benchmark](../how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md)
|
||||
- [Configure Alerts for Periodic Scan on a Schedule](../how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md)
|
||||
- [Create a Custom Benchmark Version to Run](../how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md)
|
||||
@@ -1 +1,193 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: CIS Scans
|
||||
weight: 17
|
||||
aliases:
|
||||
- /rancher/v2.5/en/cis-scans/v2.5
|
||||
- /rancher/v2.x/en/cis-scans/
|
||||
- /rancher/v2.x/en/cis-scans/v2.5/
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.
|
||||
|
||||
The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench,</a> an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes <a href="https://github.com/vmware-tanzu/sonobuoy" target="_blank">Sonobuoy</a> for report aggregation.
|
||||
|
||||
- [Changes in Rancher v2.5](#changes-in-rancher-v2-5)
|
||||
- [About the CIS Benchmark](#about-the-cis-benchmark)
|
||||
- [About the Generated Report](#about-the-generated-report)
|
||||
- [Test Profiles](#test-profiles)
|
||||
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
|
||||
- [Roles-based Access Control](#roles-based-access-control)
|
||||
- [Configuration](#configuration)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
|
||||
# Changes in Rancher v2.5
|
||||
|
||||
We now support running CIS scans on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE. Previously it was only supported to run CIS scans on RKE Kubernetes clusters.
|
||||
|
||||
In Rancher v2.4, the CIS scan tool was available from the **cluster manager** in the Rancher UI. Now it is available in the **Cluster Explorer** and it can be enabled and deployed using a Helm chart. It can be installed from the Rancher UI, but it can also be installed independently of Rancher. It deploys a CIS scan operator for the cluster, and deploys Kubernetes custom resources for cluster scans. The custom resources can be managed directly from the **Cluster Explorer.**
|
||||
|
||||
In v1 of the CIS scan tool, which was available in Rancher v2.4 through the cluster manager, recurring scans could be scheduled. The ability to schedule recurring scans is now also available for CIS v2 from Rancher v2.5.4.
|
||||
|
||||
Support for alerting for the cluster scan results is now also available from Rancher v2.5.4.
|
||||
|
||||
In Rancher v2.4, permissive and hardened profiles were included. In Rancher v2.5.0 and in v2.5.4, more profiles were included.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Profiles in v2.5.4">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- EKS
|
||||
- GKE
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 permissive 1.5
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Profiles in v2.5.0-v2.5.3">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- RKE permissive
|
||||
- RKE hardened
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
<br/>
|
||||
|
||||
|
||||
The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned and the Rancher version:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="v2.5.4">
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.6 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.5 profile is the default.
|
||||
- For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="v2.5.0-v2.5.3">
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.5 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE permissive profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For cluster types other than RKE, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> **Note:** CIS v1 cannot run on a cluster when CIS v2 is deployed. In other words, after `rancher-cis-benchmark` is installed, you can't run scans by going to the Cluster Manager view in the Rancher UI and clicking <b>Tools > CIS Scans.</b>
|
||||
|
||||
# About the CIS Benchmark
|
||||
|
||||
The Center for Internet Security is a 501(c\)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.
|
||||
|
||||
CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.
|
||||
|
||||
The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is
|
||||
<a href="https://learn.cisecurity.org/benchmarks" target="_blank">here.</a>
|
||||
|
||||
# About the Generated Report
|
||||
|
||||
Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.
|
||||
|
||||
From Rancher v2.5.4, the scan uses the CIS Benchmark v1.6 by default. In Rancher v2.5.0-2.5.3, the CIS Benchmark v1.5. is used.
|
||||
|
||||
The Benchmark version is included in the generated report.
|
||||
|
||||
The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.
|
||||
|
||||
Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's [self-assessment guide](./rancher-security.md#the-cis-benchmark-and-self-assessment) for the corresponding Kubernetes version.
|
||||
|
||||
The report contains the following information:
|
||||
|
||||
| Column in Report | Description |
|
||||
|------------------|-------------|
|
||||
| `id` | The ID number of the CIS Benchmark. |
|
||||
| `description` | The description of the CIS Benchmark test. |
|
||||
| `remediation` | What needs to be fixed in order to pass the test. |
|
||||
| `state` | Indicates if the test passed, failed, was skipped, or was not applicable. |
|
||||
| `node_type` | The node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes. |
|
||||
| `audit` | This is the audit check that `kube-bench` runs for this test. |
|
||||
| `audit_config` | Any configuration applicable to the audit script. |
|
||||
| `test_info` | Test-related info as reported by `kube-bench`, if any. |
|
||||
| `commands` | Test-related commands as reported by `kube-bench`, if any. |
|
||||
| `config_commands` | Test-related configuration data as reported by `kube-bench`, if any. |
|
||||
| `actual_value` | The test's actual value, present if reported by `kube-bench`. |
|
||||
| `expected_result` | The test's expected result, present if reported by `kube-bench`. |
|
||||
|
||||
Refer to the [table in the cluster hardening guide](./rancher-security.md) for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.
|
||||
|
||||
# Test Profiles
|
||||
|
||||
The following profiles are available:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Profiles in v2.5.4">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- EKS
|
||||
- GKE
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 permissive 1.5
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Profiles in v2.5.0-v2.5.3">
|
||||
|
||||
- Generic CIS 1.5
|
||||
- RKE permissive
|
||||
- RKE hardened
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You also have the ability to customize a profile by saving a set of tests to skip.
|
||||
|
||||
All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.
|
||||
|
||||
There are two types of RKE cluster scan profiles:
|
||||
|
||||
- **Permissive:** This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
|
||||
- **Hardened:** This profile will not skip any tests, except for the non-applicable tests.
|
||||
|
||||
The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.
|
||||
|
||||
In order to pass the "Hardened" profile, you will need to follow the steps on the [hardening guide](./rancher-security.md#rancher-hardening-guide) and use the `cluster.yml` defined in the hardening guide to provision a hardened cluster.
|
||||
|
||||
# About Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to [this page](../explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md).
|
||||
|
||||
For now, only user-defined skipped tests are marked as skipped in the generated report.
|
||||
|
||||
Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.
|
||||
|
||||
# Roles-based Access Control
|
||||
|
||||
For information about permissions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md).
|
||||
|
||||
# Configuration
|
||||
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](../explanations/integrations-in-rancher/cis-scans/configuration-reference.md).
|
||||
|
||||
# How-to Guides
|
||||
|
||||
Please refer [here](../pages-for-subheaders/cis-scan-guides.md) for how-to guides on CIS scans.
|
||||
@@ -1,129 +1,5 @@
|
||||
---
|
||||
title: CLI with Rancher
|
||||
description: Interact with Rancher using command line interface (CLI) tools from your workstation.
|
||||
weight: 21
|
||||
---
|
||||
|
||||
- [Rancher CLI](#rancher-cli)
|
||||
- [Download Rancher CLI](#download-rancher-cli)
|
||||
- [Requirements](#requirements)
|
||||
- [CLI Authentication](#cli-authentication)
|
||||
- [Project Selection](#project-selection)
|
||||
- [Commands](#commands)
|
||||
- [Rancher CLI Help](#rancher-cli-help)
|
||||
- [Limitations](#limitations)
|
||||
- [kubectl](#kubectl)
|
||||
- [kubectl Utility](#kubectl-utility)
|
||||
- [Authentication with kubectl and kubeconfig Tokens with TTL](#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl)
|
||||
|
||||
# Rancher CLI
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
### Download Rancher CLI
|
||||
|
||||
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/ranchcli/releases) for direct downloads of the binary.
|
||||
|
||||
### Requirements
|
||||
|
||||
After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:
|
||||
|
||||
- Your Rancher Server URL, which is used to connect to Rancher Server.
|
||||
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key](../reference-guides/user-settings/api-keys.md).
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `<BEARER_TOKEN>` and `<SERVER_URL>` with your information):
|
||||
|
||||
```bash
|
||||
$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>
|
||||
```
|
||||
|
||||
If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.
|
||||
|
||||
### Project Selection
|
||||
|
||||
Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
|
||||
|
||||
**Example: `./rancher context switch` Output**
|
||||
```
|
||||
User:rancher-cli-directory user$ ./rancher context switch
|
||||
NUMBER CLUSTER NAME PROJECT ID PROJECT NAME
|
||||
1 cluster-2 c-7q96s:p-h4tmb project-2
|
||||
2 cluster-2 c-7q96s:project-j6z6d Default
|
||||
3 cluster-1 c-lchzv:p-xbpdt project-1
|
||||
4 cluster-1 c-lchzv:project-s2mch Default
|
||||
Select a Project:
|
||||
```
|
||||
|
||||
After you enter a number, the console displays a message that you've changed projects.
|
||||
|
||||
```
|
||||
INFO[0005] Setting new context to project project-1
|
||||
INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json
|
||||
```
|
||||
|
||||
Ensure you can run `rancher kubectl get pods` successfully.
|
||||
|
||||
### Commands
|
||||
|
||||
The following commands are available for use in Rancher CLI.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `apps, [app]` | Performs operations on catalog applications (i.e., individual [Helm charts](https://docs.helm.sh/developing_charts/)) or Rancher charts. |
|
||||
| `catalog` | Performs operations on [catalogs](./helm-charts-in-rancher.md). |
|
||||
| `clusters, [cluster]` | Performs operations on your [clusters](kubernetes-clusters-in-rancher-setup.md). |
|
||||
| `context` | Switches between Rancher [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). For an example, see [Project Selection](#project-selection). |
|
||||
| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) and [workloads](workloads-and-pods.md)). Specify resources by name or ID. |
|
||||
| `kubectl` |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). |
|
||||
| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). |
|
||||
| `namespaces, [namespace]` |Performs operations on namespaces. |
|
||||
| `nodes, [node]` |Performs operations on nodes. |
|
||||
| `projects, [project]` | Performs operations on [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). |
|
||||
| `ps` | Displays [workloads](workloads-and-pods.md) in a project. |
|
||||
| `settings, [setting]` | Shows the current settings for your Rancher Server. |
|
||||
| `ssh` | Connects to one of your cluster nodes using the SSH protocol. |
|
||||
| `help, [h]` | Shows a list of commands or help for one command. |
|
||||
|
||||
|
||||
### Rancher CLI Help
|
||||
|
||||
Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands.
|
||||
|
||||
All commands accept the `--help` flag, which documents each command's usage.
|
||||
|
||||
### Limitations
|
||||
|
||||
The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](helm-charts-in-rancher.md).
|
||||
|
||||
# kubectl
|
||||
|
||||
Interact with Rancher using kubectl.
|
||||
|
||||
### kubectl Utility
|
||||
|
||||
Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
|
||||
Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file.
|
||||
|
||||
Run `kubectl cluster-info` or `kubectl get pods` successfully.
|
||||
|
||||
### Authentication with kubectl and kubeconfig Tokens with TTL
|
||||
|
||||
_Requirements_
|
||||
|
||||
If admins have [enforced TTL on kubeconfig tokens](../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](cli-with-rancher.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.
|
||||
|
||||
This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:
|
||||
|
||||
1. Local
|
||||
2. Active Directory (LDAP only)
|
||||
3. FreeIPA
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server.
|
||||
The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../reference-guides/about-the-api/api-tokens.md#deleting-tokens).
|
||||
Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
Interact with Rancher using command line interface (CLI) tools from your workstation. The following docs will describe the [Rancher CLI](../reference-guides/cli-with-rancher/rancher-cli.md) and [kubectl Utility](../reference-guides/cli-with-rancher/kubectl-utility).
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Downstream Cluster Configuration
|
||||
---
|
||||
|
||||
The following docs will discuss [node template configuration](./node-template-configuration.md).
|
||||
@@ -27,30 +27,7 @@ If no value has been set, Rancher uses the default value.
|
||||
|
||||
Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.
|
||||
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect.
|
||||
|
||||
> **Note:** There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.
|
||||
|
||||
The following is a list of the feature flags available in Rancher:
|
||||
|
||||
- `fleet`: Rancher comes with [Fleet](../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md) preinstalled in v2.5+.
|
||||
- `istio-virtual-service-ui`: This feature enables a [UI to create, read, update, and delete Istio virtual services and destination rules](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md), which are traffic management features of Istio.
|
||||
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.md) In other words, it enables types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
The below table shows the availability and default value for feature flags in Rancher:
|
||||
|
||||
| Feature Flag Name | Default Value | Status | Available as of | Rancher Restart Required? |
|
||||
| ----------------------------- | ------------- | ------------ | --------------- |---|
|
||||
| `dashboard` | `true` | Experimental | v2.4.0 | x |
|
||||
| `dashboard` | `true` | GA* and no longer a feature flag | v2.5.0 | x |
|
||||
| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | |
|
||||
| `istio-virtual-service-ui` | `true` | GA* | v2.3.2 | |
|
||||
| `proxy` | `false` | Experimental | v2.4.0 | |
|
||||
| `proxy` | N/A | Discontinued | v2.5.0 | |
|
||||
| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | |
|
||||
| `fleet` | `true` | GA* | v2.5.0 | |
|
||||
|
||||
\* Generally Available. This feature is included in Rancher and it is not experimental.
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../reference-guides/installation-references/feature-flags.md) for more information.
|
||||
|
||||
# Enabling Features when Starting Rancher
|
||||
|
||||
@@ -58,20 +35,27 @@ When you install Rancher, enable the feature you want with a feature flag. The c
|
||||
|
||||
### Enabling Features for Kubernetes Installs
|
||||
|
||||
> **Note:** Values set from the Rancher API will override the value passed in through the command line.
|
||||
:::note
|
||||
|
||||
Values set from the Rancher API will override the value passed in through the command line.
|
||||
|
||||
:::
|
||||
|
||||
When installing Rancher with a Helm chart, use the `--set` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
|
||||
|
||||
```
|
||||
helm install rancher-latest/rancher \
|
||||
--name rancher \
|
||||
helm install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES'
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
Note: If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
:::note
|
||||
|
||||
If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
:::
|
||||
|
||||
### Rendering the Helm Chart for Air Gap Installations
|
||||
|
||||
@@ -79,10 +63,7 @@ For an air gap installation of Rancher, you need to add a Helm chart repository
|
||||
|
||||
Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.
|
||||
|
||||
The Helm 3 command is as follows:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.5.8+">
|
||||
The Helm command is as follows:
|
||||
|
||||
```
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
@@ -97,38 +78,6 @@ helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.5.8">
|
||||
|
||||
```
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES'
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The Helm 2 command is as follows:
|
||||
|
||||
```
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES'
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
### Enabling Features for Docker Installs
|
||||
|
||||
When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
|
||||
@@ -143,17 +92,17 @@ docker run -d -p 80:80 -p 443:443 \
|
||||
|
||||
# Enabling Features with the Rancher UI
|
||||
|
||||
1. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. You will see a list of experimental features.
|
||||
1. To enable a feature, go to the disabled feature you want to enable and click **⋮ > Activate.**
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Click **Feature Flags**.
|
||||
1. To enable a feature, go to the disabled feature you want to enable and click **⋮ > Activate**.
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher UI
|
||||
|
||||
1. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. You will see a list of experimental features.
|
||||
1. To disable a feature, go to the enabled feature you want to disable and click **⋮ > Deactivate.**
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Click **Feature Flags**. You will see a list of experimental features.
|
||||
1. To disable a feature, go to the enabled feature you want to disable and click **⋮ > Deactivate**.
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
|
||||
@@ -161,11 +110,11 @@ docker run -d -p 80:80 -p 443:443 \
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
|
||||
1. In the **Value** drop-down menu, click **True.**
|
||||
1. Click **Show Request.**
|
||||
1. Click **Send Request.**
|
||||
1. Click **Close.**
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **True**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
@@ -173,10 +122,10 @@ docker run -d -p 80:80 -p 443:443 \
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
|
||||
1. In the **Value** drop-down menu, click **False.**
|
||||
1. Click **Show Request.**
|
||||
1. Click **Send Request.**
|
||||
1. Click **Close.**
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **False**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
**Result:** The feature is disabled.
|
||||
@@ -1 +1,93 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Fleet - GitOps at Scale
|
||||
---
|
||||
|
||||
_Available as of Rancher v2.5_
|
||||
|
||||
Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It’s also lightweight enough that it works great for a [single cluster](https://fleet.rancher.io/single-cluster-install/) too, but it really shines when you get to a [large scale](https://fleet.rancher.io/multi-cluster-install/). By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.
|
||||
|
||||
Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.
|
||||
|
||||
- [Architecture](../explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.md)
|
||||
- [Accessing Fleet in the Rancher UI](#accessing-fleet-in-the-rancher-ui)
|
||||
- [Windows Support](../explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md)
|
||||
- [GitHub Repository](#github-repository)
|
||||
- [Use Fleet Behind a Proxy](../explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md)
|
||||
- [Helm Chart Dependencies](#helm-chart-dependencies)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Documentation](#documentation)
|
||||
|
||||
# Architecture
|
||||
|
||||
For information about how Fleet works, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.md).
|
||||
|
||||
# Accessing Fleet in the Rancher UI
|
||||
|
||||
Fleet comes preinstalled in Rancher v2.5. Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following **gitops** practice. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer [here](https://fleet.rancher.io/troubleshooting/).
|
||||
|
||||
Follow the steps below to access Continuous Delivery in the Rancher UI:
|
||||
|
||||
1. Click **Cluster Explorer** in the Rancher UI.
|
||||
|
||||
1. In the top left dropdown menu, click **Cluster Explorer > Continuous Delivery**.
|
||||
|
||||
1. Select your namespace at the top of the menu, noting the following:
|
||||
|
||||
- By default, **fleet-default** is selected which includes all downstream clusters that are registered through Rancher.
|
||||
|
||||
- You may switch to **fleet-local**, which only contains the **local** cluster, or you may create your own workspace to which you may assign and move clusters.
|
||||
|
||||
- You can then manage clusters by clicking on **Clusters** on the left navigation bar.
|
||||
|
||||
1. Click on **Gitrepos** on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.
|
||||
|
||||
1. Select your [git repository](https://fleet.rancher.io/gitrepo-add/) and [target clusters/cluster group](https://fleet.rancher.io/gitrepo-structure/). You can also create the cluster group in the UI by clicking on **Cluster Groups** from the left navigation bar.
|
||||
|
||||
1. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.
|
||||
|
||||
# Windows Support
|
||||
|
||||
_Available as of v2.5.6_
|
||||
|
||||
For details on support for clusters with Windows nodes, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md).
|
||||
|
||||
# GitHub Repository
|
||||
|
||||
The Fleet Helm charts are available [here](https://github.com/rancher/fleet/releases/tag/v0.3.10).
|
||||
|
||||
# Using Fleet Behind a Proxy
|
||||
|
||||
_Available as of v2.5.8_
|
||||
|
||||
For details on using Fleet behind a proxy, see [this page](../explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md).
|
||||
|
||||
# Helm Chart Dependencies
|
||||
|
||||
In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run `helm install`, your installation will fail because the dependencies will be missing.
|
||||
|
||||
The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run `helm dependencies update $chart` OR run `helm dependencies build $chart` locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
- **Known Issue**: Fleet becomes inoperable after a restore using the [backup-restore-operator](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place.
|
||||
|
||||
- **Temporary Workaround**:
|
||||
|
||||
1. Find the two service account tokens listed in the fleet-controller and the fleet-controller-bootstrap service accounts. These are under the fleet-system namespace of the local cluster.
|
||||
1. Remove the non-existent token secret. Doing so allows for only one entry to be present for the service account token secret that actually exists.
|
||||
1. Delete the fleet-controller Pod in the fleet-system namespace to reschedule.
|
||||
1. After the service account token issue is resolved, you can force redeployment of the fleet-agents. In the Rancher UI, go to **☰ > Cluster Management**, click on **Clusters** page, then click **Force Update**.
|
||||
1. If the fleet-agent bundles remain in a `Modified` state after Step 4, update the field `spec.forceSyncGeneration` for the fleet-agent bundle to force re-creation.
|
||||
|
||||
---
|
||||
|
||||
- **Known Issue**: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the [backup-restore-operator](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place.
|
||||
|
||||
- **Temporary Workaround**: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs [here](https://github.com/rancher/backup-restore-operator#user-flow).
|
||||
|
||||
# Documentation
|
||||
|
||||
The Fleet documentation is at https://fleet.rancher.io/.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Installation References
|
||||
---
|
||||
|
||||
Please see the following reference guides for other installation resources: [Rancher Helm chart options](../reference-guides/installation-references/helm-chart-options.md), [TLS settings](../reference-guides/installation-references/tls-settings.md), and [feature flags](../reference-guides/installation-references/feature-flags.md).
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user