From 4cf46f901bb87a1b932fd3eb2586fbff23800a44 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Thu, 1 Sep 2022 12:34:19 -0400 Subject: [PATCH 1/6] Updating new site with new docs content --- docs/contribute-to-rancher.md | 2 +- docs/explanations.md | 7 ++- docs/faq.md | 2 +- docs/getting-started.md | 12 +++++- docs/how-to-guides.md | 7 ++- ...-alerts-for-periodic-scan-on-a-schedule.md | 43 ++++++++++++++++++- .../install-rancher-cis-benchmark.md | 13 +++++- .../cis-scan-guides/run-a-scan.md | 24 ++++++++++- .../uninstall-rancher-cis-benchmark.md | 13 +++++- docs/reference-guides.md | 13 +++++- docs/troubleshooting.md | 2 +- 11 files changed, 127 insertions(+), 11 deletions(-) diff --git a/docs/contribute-to-rancher.md b/docs/contribute-to-rancher.md index 44017019ff6..ee2664adae1 100644 --- a/docs/contribute-to-rancher.md +++ b/docs/contribute-to-rancher.md @@ -1,6 +1,6 @@ --- title: Contributing to Rancher -weight: 27 +weight: 700 --- This section explains the repositories used for Rancher, how to build the repositories, and what information to include when you file an issue. diff --git a/docs/explanations.md b/docs/explanations.md index fa42a3bae89..a8ce4af1e5a 100644 --- a/docs/explanations.md +++ b/docs/explanations.md @@ -1 +1,6 @@ - \ No newline at end of file +--- +title: Explanations +weight: 400 +--- + +**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. \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md index d92c75835d5..50a2901350c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ --- title: FAQ -weight: 25 +weight: 500 --- This FAQ is a work in progress designed to answers the questions our users most frequently ask about Rancher v2.x. diff --git a/docs/getting-started.md b/docs/getting-started.md index fa42a3bae89..d8e5d8383e9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1 +1,11 @@ - \ No newline at end of file +--- +title: Getting Started +weight: 100 +--- + +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], [quick start guides], and the [installation and upgrade] sections for more. + diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md index fa42a3bae89..45de2fb1889 100644 --- a/docs/how-to-guides.md +++ b/docs/how-to-guides.md @@ -1 +1,6 @@ - \ No newline at end of file +--- +title: How-to Guides +weight: 200 +--- + +**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] and [advanced user guides]. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md index fa42a3bae89..1da9bf441f4 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md @@ -1 +1,42 @@ - \ No newline at end of file +--- +title: Configure Alerts for Periodic Scan on a Schedule +weight: 8 +--- + +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](https://rancher.com/docs/rancher/v2.6/en/monitoring-alerting/configuration/). + +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](https://rancher.com/docs/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#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. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md index fa42a3bae89..cdfa9cd316e 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Install Rancher CIS Benchmark +weight: 1 +--- + +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. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md index fa42a3bae89..f1709b9953c 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md @@ -1 +1,23 @@ - \ No newline at end of file +--- +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. + +:::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. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md index fa42a3bae89..4d788eb4cc1 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +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. 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. \ No newline at end of file diff --git a/docs/reference-guides.md b/docs/reference-guides.md index fa42a3bae89..87b557c629f 100644 --- a/docs/reference-guides.md +++ b/docs/reference-guides.md @@ -1 +1,12 @@ - \ No newline at end of file +--- +title: Reference Guides +weight: 300 +--- + +**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] and [cluster configuration guides]. \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index c514b31b38d..9c990589f93 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -weight: 26 +weight: 600 --- This section contains information to help you troubleshoot issues when using Rancher. From 2f945160bfb59f34a86a3f57587b659aaf9c1af6 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 2 Sep 2022 10:13:32 -0400 Subject: [PATCH 2/6] Updating new docs --- ...-alerts-for-periodic-scan-on-a-schedule.md | 11 +- ...reate-a-custom-benchmark-version-to-run.md | 11 +- ...able-alerting-for-rancher-cis-benchmark.md | 22 +- .../install-rancher-cis-benchmark.md | 2 +- .../run-a-scan-periodically-on-a-schedule.md | 22 +- .../cis-scan-guides/run-a-scan.md | 2 +- .../cis-scan-guides/skip-tests.md | 36 ++- .../uninstall-rancher-cis-benchmark.md | 6 +- .../cis-scan-guides/view-reports.md | 14 +- .../advanced-user-guides.md | 8 +- docs/pages-for-subheaders/cis-scan-guides.md | 305 +----------------- docs/pages-for-subheaders/cis-scans.md | 112 ++++++- docs/pages-for-subheaders/new-user-guides.md | 10 +- 13 files changed, 248 insertions(+), 313 deletions(-) diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md index 1da9bf441f4..2eb74ba76b6 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md @@ -11,15 +11,14 @@ 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 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. -- 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 -:::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.](monitoring-alertincis-scans/configuration) -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](https://rancher.com/docs/rancher/v2.6/en/monitoring-alerting/configuration/). - -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](https://rancher.com/docs/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts). +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.](monitoring-alertincis-scans/configuration/receiver/#example-route-config-for-cis-scan-alerts) ::: diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md index fa42a3bae89..167d23785b2 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md @@ -1 +1,10 @@ - \ No newline at end of file +--- +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. + +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) \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md index fa42a3bae89..0877fec3eba 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md @@ -1 +1,21 @@ - \ No newline at end of file +--- +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. + +:::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.](monitoring-alertincis-scans/configuration) + +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.](monitoring-alertincis-scans/configuration/receiver/#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 +``` \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md index cdfa9cd316e..7c9cb110592 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md @@ -6,7 +6,7 @@ weight: 1 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 **CIS Benchmark** 1. Click **Install**. **Result:** The CIS scan application is deployed on the Kubernetes cluster. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md index fa42a3bae89..3b04bef2676 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md @@ -1 +1,21 @@ - \ No newline at end of file +--- +title: Run a Scan Periodically on a Schedule +weight: 4 +--- + +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 cron schedule expression 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. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md index f1709b9953c..1825f97b172 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md @@ -7,7 +7,7 @@ When a ClusterScan custom resource is created, it launches a new CIS scan on the :::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. +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. ::: diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md index fa42a3bae89..cd0a1d9ef92 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md @@ -1 +1,35 @@ - \ No newline at end of file +--- +title: Skip Tests +weight: 5 +--- + +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: "" + 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`. diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md index 4d788eb4cc1..65b6ccf7b1a 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md @@ -3,10 +3,8 @@ 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. Go to the **cis-operator-system** namespace and check the boxes next to **rancher-cis-benchmark-crd** and **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. \ No newline at end of file diff --git a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md index fa42a3bae89..72b6f4f1890 100644 --- a/docs/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md +++ b/docs/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md @@ -1 +1,13 @@ - \ No newline at end of file +--- +title: View Reports +weight: 6 +--- + +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. \ No newline at end of file diff --git a/docs/pages-for-subheaders/advanced-user-guides.md b/docs/pages-for-subheaders/advanced-user-guides.md index fa42a3bae89..e4b8c16e1e4 100644 --- a/docs/pages-for-subheaders/advanced-user-guides.md +++ b/docs/pages-for-subheaders/advanced-user-guides.md @@ -1 +1,7 @@ - \ No newline at end of file +--- +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. \ No newline at end of file diff --git a/docs/pages-for-subheaders/cis-scan-guides.md b/docs/pages-for-subheaders/cis-scan-guides.md index f61760c0317..d4dbf044ac2 100644 --- a/docs/pages-for-subheaders/cis-scan-guides.md +++ b/docs/pages-for-subheaders/cis-scan-guides.md @@ -1,296 +1,15 @@ --- -title: CIS Scans -weight: 17 +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 kube-bench, 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 Sonobuoy 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) -- [How-to Guides](#how-to-guides) - - [Installing CIS Benchmark](#installing-cis-benchmark) - - [Uninstalling CIS Benchmark](#uninstalling-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) - - -# 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 -here. - -# 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 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 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 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. - -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. - -# Configuration - -For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to this page. - -# 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 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. - -### Uninstalling 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. - -### 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. 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. -### Running 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 cron schedule expression 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 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: "" - 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 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. - -### Enabling 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.](monitoring-alertincis-scans/configuration) - -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.](monitoring-alertincis-scans/configuration/receiver/#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 -``` - -### Configuring Alerts for a 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.](monitoring-alertincis-scans/configuration) - -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.](monitoring-alertincis-scans/configuration/receiver/#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. - -### Creating 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) +The following tutorials will guide you through: + +- Installing `rancher-cis-benchmark` +- Uninstalling `rancher-cis-benchmark` +- Running a scan +- Running a scan periodically on a schedule +- Skilling tests +- Viewing reports +- Enabling alerting for `rancher-cis-benchmark` +- Configuring alerts for a periodic scan on a schedule +- Creating a custom benchmark version for running a cluster scan \ No newline at end of file diff --git a/docs/pages-for-subheaders/cis-scans.md b/docs/pages-for-subheaders/cis-scans.md index fa42a3bae89..159b7bc78de 100644 --- a/docs/pages-for-subheaders/cis-scans.md +++ b/docs/pages-for-subheaders/cis-scans.md @@ -1 +1,111 @@ - \ No newline at end of file +--- +title: CIS Scans +weight: 17 +--- + +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 kube-bench, 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 Sonobuoy 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 +here. + +# 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 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 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 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. + +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. + +# Configuration + +For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to this page. \ No newline at end of file diff --git a/docs/pages-for-subheaders/new-user-guides.md b/docs/pages-for-subheaders/new-user-guides.md index fa42a3bae89..e2e667395c3 100644 --- a/docs/pages-for-subheaders/new-user-guides.md +++ b/docs/pages-for-subheaders/new-user-guides.md @@ -1 +1,9 @@ - \ No newline at end of file +--- +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. \ No newline at end of file From 4fa86ce0685fc7d8f527edc6a6c516e5a3d23369 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 2 Sep 2022 11:17:34 -0400 Subject: [PATCH 3/6] Updating files --- docs/getting-started.md | 3 +- .../introduction/what-are-divio-docs.md | 113 +++++++++++++++++- docs/how-to-guides.md | 3 +- docs/pages-for-subheaders/cis-scan-guides.md | 12 +- docs/pages-for-subheaders/introduction.md | 6 +- docs/reference-guides.md | 5 +- 6 files changed, 122 insertions(+), 20 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index d8e5d8383e9..72ea1bf1c86 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,11 +1,10 @@ --- title: Getting Started -weight: 100 --- 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], [quick start guides], and the [installation and upgrade] sections for more. +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. diff --git a/docs/getting-started/introduction/what-are-divio-docs.md b/docs/getting-started/introduction/what-are-divio-docs.md index fa42a3bae89..0f2a412eae5 100644 --- a/docs/getting-started/introduction/what-are-divio-docs.md +++ b/docs/getting-started/introduction/what-are-divio-docs.md @@ -1 +1,112 @@ - \ No newline at end of file +--- +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](../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. + +## 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](../../pages-for-subheaders/integrations-in-rancher.md), this subsection has been added under **references**. + +Examples of some of these integrations are [Harvester](../../explanations/integrations-in-rancher/harvester.md) and [NeuVector](../../explanations/integrations-in-rancher/neuvector.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. \ No newline at end of file diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md index 45de2fb1889..87165f2a758 100644 --- a/docs/how-to-guides.md +++ b/docs/how-to-guides.md @@ -1,6 +1,5 @@ --- title: How-to Guides -weight: 200 --- -**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] and [advanced user guides]. \ No newline at end of file +**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). diff --git a/docs/pages-for-subheaders/cis-scan-guides.md b/docs/pages-for-subheaders/cis-scan-guides.md index d4dbf044ac2..d0011040a07 100644 --- a/docs/pages-for-subheaders/cis-scan-guides.md +++ b/docs/pages-for-subheaders/cis-scan-guides.md @@ -2,14 +2,4 @@ title: CIS Scan Guides --- -The following tutorials will guide you through: - -- Installing `rancher-cis-benchmark` -- Uninstalling `rancher-cis-benchmark` -- Running a scan -- Running a scan periodically on a schedule -- Skilling tests -- Viewing reports -- Enabling alerting for `rancher-cis-benchmark` -- Configuring alerts for a periodic scan on a schedule -- Creating a custom benchmark version for running a cluster scan \ No newline at end of file +In the following tutorials, you will 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). \ No newline at end of file diff --git a/docs/pages-for-subheaders/introduction.md b/docs/pages-for-subheaders/introduction.md index fa42a3bae89..d11bed52a24 100644 --- a/docs/pages-for-subheaders/introduction.md +++ b/docs/pages-for-subheaders/introduction.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +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. \ No newline at end of file diff --git a/docs/reference-guides.md b/docs/reference-guides.md index 87b557c629f..d2e85baa0b1 100644 --- a/docs/reference-guides.md +++ b/docs/reference-guides.md @@ -1,12 +1,11 @@ --- title: Reference Guides -weight: 300 --- **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. +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] and [cluster configuration guides]. \ No newline at end of file +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). From d6d4b375327b83a3faa160b24bfb1fe1a987ca3c Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 2 Sep 2022 11:51:13 -0400 Subject: [PATCH 4/6] Updating files --- .../authentication-config/configure-active-directory.md | 2 +- .../authentication-config/configure-azure-ad.md | 2 +- .../authentication-config/configure-freeipa.md | 2 +- .../authentication-config/configure-github.md | 2 +- .../authentication-config/configure-google-oauth.md | 2 +- .../authentication-config/configure-keycloak-oidc.md | 2 +- .../authentication-config/configure-keycloak-saml.md | 2 +- .../authentication-config/configure-okta-saml.md | 2 +- .../authentication-config/configure-pingidentity.md | 2 +- docs/pages-for-subheaders/authentication-config.md | 6 +++++- 10 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md index 57c4b3afbb0..c1e4a05a3b0 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md @@ -1,5 +1,5 @@ --- -title: Configuring Active Directory (AD) +title: Configure Active Directory (AD) weight: 1112 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md index 688e4fc5ff6..6257f175bd1 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md @@ -1,5 +1,5 @@ --- -title: Configuring Azure AD +title: Configure Azure AD weight: 1115 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md index 275e9ccf38b..1dc551a9a14 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md @@ -1,5 +1,5 @@ --- -title: Configuring FreeIPA +title: Configure FreeIPA weight: 1114 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md index b1634e3e27f..56859c962f0 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md @@ -1,5 +1,5 @@ --- -title: Configuring GitHub +title: Configure GitHub weight: 1116 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md index 54a6c6d0c00..9a0c098ae37 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md @@ -1,5 +1,5 @@ --- -title: Configuring Google OAuth +title: Configure Google OAuth weight: 10 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md index 6c96c5d5152..146e834e48f 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.md @@ -1,5 +1,5 @@ --- -title: Configuring Keycloak (OIDC) +title: Configure Keycloak (OIDC) description: Create a Keycloak OpenID Connect (OIDC) client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins weight: 1200 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md index 2283169b6e5..db51fa5a7df 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.md @@ -1,5 +1,5 @@ --- -title: Configuring Keycloak (SAML) +title: Configure Keycloak (SAML) description: Create a Keycloak SAML client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins weight: 1200 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md index f099f0b8661..b39e0c951be 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md @@ -1,5 +1,5 @@ --- -title: Configuring Okta (SAML) +title: Configure Okta (SAML) weight: 1210 --- diff --git a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md index f61b55eb786..042a20bfb01 100644 --- a/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md +++ b/docs/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md @@ -1,5 +1,5 @@ --- -title: Configuring PingIdentity (SAML) +title: Configure PingIdentity (SAML) weight: 1200 --- diff --git a/docs/pages-for-subheaders/authentication-config.md b/docs/pages-for-subheaders/authentication-config.md index fa42a3bae89..62f8443fbf1 100644 --- a/docs/pages-for-subheaders/authentication-config.md +++ b/docs/pages-for-subheaders/authentication-config.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +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). \ No newline at end of file From 8c3ff04130b69641339913cfe794676d9adb8962 Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 2 Sep 2022 13:47:40 -0400 Subject: [PATCH 5/6] Updating files with new/moved content --- docs/pages-for-subheaders/cli-with-rancher.md | 130 +----------------- .../downstream-cluster-configuration.md | 6 +- .../enable-experimental-features.md | 38 +---- .../installation-references.md | 6 +- docs/pages-for-subheaders/selinux-rpm.md | 80 +---------- .../cli-with-rancher/kubectl-utility.md | 39 +++++- .../cli-with-rancher/rancher-cli.md | 98 ++++++++++++- .../installation-references/feature-flags.md | 38 ++++- .../selinux-rpm/about-rancher-selinux.md | 68 ++++++++- .../selinux-rpm/about-rke2-selinux.md | 10 +- 10 files changed, 261 insertions(+), 252 deletions(-) diff --git a/docs/pages-for-subheaders/cli-with-rancher.md b/docs/pages-for-subheaders/cli-with-rancher.md index e43371cdc8a..031f2dcde9c 100644 --- a/docs/pages-for-subheaders/cli-with-rancher.md +++ b/docs/pages-for-subheaders/cli-with-rancher.md @@ -1,133 +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. - -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](../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 `` and `` with your information): - -```bash -$ ./rancher login https:// --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]({{}}/rancher/v2.6/helm-charts). | -| `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). diff --git a/docs/pages-for-subheaders/downstream-cluster-configuration.md b/docs/pages-for-subheaders/downstream-cluster-configuration.md index fa42a3bae89..2d15adaa3b8 100644 --- a/docs/pages-for-subheaders/downstream-cluster-configuration.md +++ b/docs/pages-for-subheaders/downstream-cluster-configuration.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +title: Downstream Cluster Configuration +--- + +Users can easily configure downstream clusters with Rancher. The following docs will discuss [node template configuration](./node-template-configuration.md) and [machine configuration](./machine-configuration.md). \ No newline at end of file diff --git a/docs/pages-for-subheaders/enable-experimental-features.md b/docs/pages-for-subheaders/enable-experimental-features.md index 39225b1a69a..d24aff21acc 100644 --- a/docs/pages-for-subheaders/enable-experimental-features.md +++ b/docs/pages-for-subheaders/enable-experimental-features.md @@ -19,43 +19,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: - -- `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/). -- `rke2`: Used to enable the ability to provision RKE2 clusters. By default, this feature flag is enabled, which allows users to attempt to provision these type of clusters. -- `fleet`: The previous `fleet` feature flag is now required to be enabled as the Fleet capabilities are leveraged within the new provisioning framework. If you had this feature flag disabled in earlier versions, upon upgrading to Rancher v2.6, the flag will automatically be enabled. See this [page](../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md) for more information. -- `continuous-delivery`: In Rancher v2.5.x, Fleet came with a GitOps feature that could not be disabled separately from Fleet. In Rancher v2.6, the `continuous-delivery` feature flag was introduced to allow the GitOps feature of Fleet to be disabled. For more information, see [this page.](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.md). -- `legacy`: There are a set of features from previous versions that are slowly being phased out of Rancher for newer iterations of the feature. This is a mix of deprecated features as well as features that will eventually be moved to newer variations in Rancher. By default, this feature flag is disabled for new installations. If you are upgrading from a previous version, this feature flag would be enabled. -- `token-hashing`: Used to enable new token-hashing feature. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically using the SHA256 algorithm. Once a token is hashed it cannot be undone. Once this feature flag is enabled, it cannot be disabled. See [hashing of tokens](../reference-guides/about-the-api/api-tokens.md) for more information. -- `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. -- `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. -- `multi-cluster-management`: Used for multi-cluster provisioning and management of Kubernetes clusters. This feature flag can only be set at install time and not changed afterwards. - -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? | -| ----------------------------- | ------------- | ------------ | --------------- |---| -| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | | -| `istio-virtual-service-ui` | `true` | GA* | v2.3.2 | | -| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | | -| `fleet` | `true` | GA* | v2.5.0 | | -| `fleet` | `true` | Can no longer be disabled | v2.6.0 | N/A | -| `continuous-delivery` | `true` | GA* | v2.6.0 | | -| `token-hashing` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | | -| `legacy` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | | -| `multi-cluster-management` | `false` | GA* | v2.5.0 | | -| `harvester` | `true` | Experimental | v2.6.1 | | -| `rke2` | `true` | Experimental | v2.6.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 diff --git a/docs/pages-for-subheaders/installation-references.md b/docs/pages-for-subheaders/installation-references.md index fa42a3bae89..0eeae0f6c4e 100644 --- a/docs/pages-for-subheaders/installation-references.md +++ b/docs/pages-for-subheaders/installation-references.md @@ -1 +1,5 @@ - \ No newline at end of file +--- +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). \ No newline at end of file diff --git a/docs/pages-for-subheaders/selinux-rpm.md b/docs/pages-for-subheaders/selinux-rpm.md index ebb2e915a58..9f1fc5c0267 100644 --- a/docs/pages-for-subheaders/selinux-rpm.md +++ b/docs/pages-for-subheaders/selinux-rpm.md @@ -14,82 +14,4 @@ After being historically used by government agencies, SELinux is now industry st Enforcing ``` -We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: `rancher-selinux` and `rke2-selinux`. - -- [rancher-selinux](#rancher-selinux) -- [rke2-selinux](#rke2-selinux) -- [Installing the rancher-selinux RPM](#installing-the-rancher-selinux-rpm) -- [Configuring the Logging Application to Work with SELinux](#configuring-the-logging-application-to-work-with-selinux) - -# 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) - -The `rancher-selinux` GitHub repository is [here.](https://github.com/rancher/rancher-selinux) - -# rke2-selinux - -rke2-selinux provides policies for RKE2. It is installed automatically when the RKE2 installer script detects that it is running on an RPM-based distro. - -The `rke2-selinux` GitHub repository is [here.](https://github.com/rancher/rke2-selinux) - -For more information about installing RKE2 on SELinux-enabled hosts, see the [RKE2 documentation.](https://docs.rke2.io/install/methods/#rpm) - -# Installing the rancher-selinux RPM - -:::note Requirement: - -The rancher-selinux RPM was tested with CentOS 7 and 8. - -::: - -### 1. Set up the yum repo - -Set up the yum repo to install `rancher-selinux` directly on all hosts in the cluster. - -In order to use the RPM repository, on a CentOS 7 or RHEL 7 system, run the following bash snippet: - -``` -# cat << EOF > /etc/yum.repos.d/rancher.repo -[rancher] -name=Rancher -baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch -enabled=1 -gpgcheck=1 -gpgkey=https://rpm.rancher.io/public.key -EOF -``` - -In order to use the RPM repository, on a CentOS 8 or RHEL 8 system, run the following bash snippet: - -``` -# cat << EOF > /etc/yum.repos.d/rancher.repo -[rancher] -name=Rancher -baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch -enabled=1 -gpgcheck=1 -gpgkey=https://rpm.rancher.io/public.key -EOF -``` -### 2. Installing the RPM - -Install the RPM: - -``` -yum -y install rancher-selinux -``` - -# Configuring the Logging Application to Work with SELinux - -:::note Requirement: - -Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. - -::: - -Applications do not automatically work once the `rancher-selinux` RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM. - -To configure the `rancher-logging` chart to be SELinux aware, change `global.seLinux.enabled` to true in the `values.yaml` when installing the chart. +We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: [`rancher-selinux`](../reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md) and [`rke2-selinux`](../reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md). \ No newline at end of file diff --git a/docs/reference-guides/cli-with-rancher/kubectl-utility.md b/docs/reference-guides/cli-with-rancher/kubectl-utility.md index fa42a3bae89..09159533e4f 100644 --- a/docs/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/docs/reference-guides/cli-with-rancher/kubectl-utility.md @@ -1 +1,38 @@ - \ No newline at end of file +--- +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](../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. \ No newline at end of file diff --git a/docs/reference-guides/cli-with-rancher/rancher-cli.md b/docs/reference-guides/cli-with-rancher/rancher-cli.md index fa42a3bae89..ced6909d259 100644 --- a/docs/reference-guides/cli-with-rancher/rancher-cli.md +++ b/docs/reference-guides/cli-with-rancher/rancher-cli.md @@ -1 +1,97 @@ - \ No newline at end of file +--- +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](../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 `` and `` with your information): + +```bash +$ ./rancher login https:// --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]({{}}/rancher/v2.6/helm-charts). | +| `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). \ No newline at end of file diff --git a/docs/reference-guides/installation-references/feature-flags.md b/docs/reference-guides/installation-references/feature-flags.md index fa42a3bae89..a3b04a3335f 100644 --- a/docs/reference-guides/installation-references/feature-flags.md +++ b/docs/reference-guides/installation-references/feature-flags.md @@ -1 +1,37 @@ - \ No newline at end of file +--- +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). + +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/). +- `rke2`: Used to enable the ability to provision RKE2 clusters. By default, this feature flag is enabled, which allows users to attempt to provision these type of clusters. +- `fleet`: The previous `fleet` feature flag is now required to be enabled as the Fleet capabilities are leveraged within the new provisioning framework. If you had this feature flag disabled in earlier versions, upon upgrading to Rancher v2.6, the flag will automatically be enabled. See this [page](../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md) for more information. +- `continuous-delivery`: In Rancher v2.5.x, Fleet came with a GitOps feature that could not be disabled separately from Fleet. In Rancher v2.6, the `continuous-delivery` feature flag was introduced to allow the GitOps feature of Fleet to be disabled. For more information, see [this page.](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.md). +- `legacy`: There are a set of features from previous versions that are slowly being phased out of Rancher for newer iterations of the feature. This is a mix of deprecated features as well as features that will eventually be moved to newer variations in Rancher. By default, this feature flag is disabled for new installations. If you are upgrading from a previous version, this feature flag would be enabled. +- `token-hashing`: Used to enable new token-hashing feature. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically using the SHA256 algorithm. Once a token is hashed it cannot be undone. Once this feature flag is enabled, it cannot be disabled. See [hashing of tokens](../reference-guides/about-the-api/api-tokens.md) for more information. +- `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. +- `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. +- `multi-cluster-management`: Used for multi-cluster provisioning and management of Kubernetes clusters. This feature flag can only be set at install time and not changed afterwards. + +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? | +| ----------------------------- | ------------- | ------------ | --------------- |---| +| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | | +| `istio-virtual-service-ui` | `true` | GA* | v2.3.2 | | +| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | | +| `fleet` | `true` | GA* | v2.5.0 | | +| `fleet` | `true` | Can no longer be disabled | v2.6.0 | N/A | +| `continuous-delivery` | `true` | GA* | v2.6.0 | | +| `token-hashing` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | | +| `legacy` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | | +| `multi-cluster-management` | `false` | GA* | v2.5.0 | | +| `harvester` | `true` | Experimental | v2.6.1 | | +| `rke2` | `true` | Experimental | v2.6.0 | | + +\* Generally Available. This feature is included in Rancher and it is not experimental. \ No newline at end of file diff --git a/docs/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md b/docs/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md index fa42a3bae89..f25aa83bf18 100644 --- a/docs/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md +++ b/docs/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md @@ -1 +1,67 @@ - \ No newline at end of file +--- +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) + +The `rancher-selinux` GitHub repository is [here.](https://github.com/rancher/rancher-selinux) + +# Installing the rancher-selinux RPM + +:::note Requirement: + +The rancher-selinux RPM was tested with CentOS 7 and 8. + +::: + +### 1. Set up the yum repo + +Set up the yum repo to install `rancher-selinux` directly on all hosts in the cluster. + +In order to use the RPM repository, on a CentOS 7 or RHEL 7 system, run the following bash snippet: + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` + +In order to use the RPM repository, on a CentOS 8 or RHEL 8 system, run the following bash snippet: + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` +### 2. Installing the RPM + +Install the RPM: + +``` +yum -y install rancher-selinux +``` + +# Configuring the Logging Application to Work with SELinux + +:::note Requirement: + +Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +::: + +Applications do not automatically work once the `rancher-selinux` RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM. + +To configure the `rancher-logging` chart to be SELinux aware, change `global.seLinux.enabled` to true in the `values.yaml` when installing the chart. \ No newline at end of file diff --git a/docs/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md b/docs/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md index fa42a3bae89..dd2ddfbb4bb 100644 --- a/docs/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md +++ b/docs/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md @@ -1 +1,9 @@ - \ No newline at end of file +--- +title: About rke2-selinux +--- + +`rke2-selinux` provides policies for RKE2. It is installed automatically when the RKE2 installer script detects that it is running on an RPM-based distro. + +The `rke2-selinux` GitHub repository is [here.](https://github.com/rancher/rke2-selinux) + +For more information about installing RKE2 on SELinux-enabled hosts, see the [RKE2 documentation.](https://docs.rke2.io/install/methods/#rpm) \ No newline at end of file From 6155c358014857035b8247c0ddec9a4addc5342c Mon Sep 17 00:00:00 2001 From: Jennifer Travinski Date: Fri, 2 Sep 2022 16:36:52 -0400 Subject: [PATCH 6/6] Updated spacing --- docs/pages-for-subheaders/cis-scan-guides.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pages-for-subheaders/cis-scan-guides.md b/docs/pages-for-subheaders/cis-scan-guides.md index f0e12788795..c4ffa2e0804 100644 --- a/docs/pages-for-subheaders/cis-scan-guides.md +++ b/docs/pages-for-subheaders/cis-scan-guides.md @@ -109,5 +109,6 @@ For information about permissions, refer to [this page](../explanations/integrat 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**_ +_**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).