mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 04:58:07 +00:00
Updating 2.0-2.4 docs with new structure; correcting other docs in 2.5, 2.6
This commit is contained in:
Jennifer Travinski
@@ -1 +1,7 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Advanced User Guides
|
||||
---
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
@@ -1 +1,6 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Authentication Config
|
||||
---
|
||||
|
||||
|
||||
In the following tutorials, you will learn how to [manage users and groups](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.md), [create local users](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.md), [configure Google OAuth](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md), [configure Active Directory (AD)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md), [configure OpenLDAP](../references/configure-openldap.md), [configure FreeIPA](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.md), [configure Azure AD](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.md), [configure GitHub](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.md), [configure Keycloak](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.md), [configure PingIdentity (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.md), [configure Okta (SAML)](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.md), [configure Shibboleth (SAML)](../pages-for-subheaders/configure-shibboleth-saml.md), and how to [configure Microsoft AD Federation Service (SAML)](../pages-for-subheaders/configure-microsoft-ad-federation-service-saml.md).
|
||||
@@ -1 +1,11 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: CIS Scan Guides
|
||||
---
|
||||
|
||||
- [Run a Scan](../how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md)
|
||||
- [Schedule Recurring Scans](../how-to-guides/advanced-user-guides/cis-scan-guides/schedule-recurring-scans.md)
|
||||
- [Skip Tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)
|
||||
- [Set Alerts](../how-to-guides/advanced-user-guides/cis-scan-guides/set-alerts.md)
|
||||
- [Delete a Report](../how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.md)
|
||||
- [Download a Report](../how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.md)
|
||||
- [Skipped and Not Applicable Tests](../how-to-guides/advanced-user-guides/cis-scan-guides/skipped-and-not-applicable-tests)
|
||||
@@ -10,13 +10,7 @@ aliases:
|
||||
_Available as of v2.4.0_
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Running a scan](#running-a-scan)
|
||||
- [Scheduling recurring scans](#scheduling-recurring-scans)
|
||||
- [Skipping tests](#skipping-tests)
|
||||
- [Setting alerts](#setting-alerts)
|
||||
- [Deleting a report](#deleting-a-report)
|
||||
- [Downloading a report](#downloading-a-report)
|
||||
- [List of skipped and not applicable tests](#list-of-skipped-and-not-applicable-tests)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
@@ -28,129 +22,6 @@ The security scan cannot run in a cluster that has Windows nodes.
|
||||
|
||||
You will only be able to see the CIS scan reports for clusters that you have access to.
|
||||
|
||||
# Running a Scan
|
||||
# How-to Guides
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > CIS Scans.**
|
||||
1. Click **Run Scan.**
|
||||
1. Choose a CIS scan profile.
|
||||
|
||||
**Result:** A report is generated and displayed in the **CIS Scans** page. To see details of the report, click the report's name.
|
||||
|
||||
# Scheduling Recurring Scans
|
||||
|
||||
Recurring scans can be scheduled to run on any RKE Kubernetes cluster.
|
||||
|
||||
To enable recurring scans, edit the advanced options in the cluster configuration during cluster creation or after the cluster has been created.
|
||||
|
||||
To schedule scans for an existing cluster:
|
||||
|
||||
1. Go to the cluster view in Rancher.
|
||||
1. Click **Tools > CIS Scans.**
|
||||
1. Click **Add Schedule.** This takes you to the section of the cluster editing page that is applicable to configuring a schedule for CIS scans. (This section can also be reached by going to the cluster view, clicking **⋮ > Edit,** and going to the **Advanced Options.**)
|
||||
1. In the **CIS Scan Enabled** field, click **Yes.**
|
||||
1. In the **CIS Scan Profile** field, choose a **Permissive** or **Hardened** profile. The corresponding CIS Benchmark version is included in the profile name. Note: Any skipped tests [defined in a separate ConfigMap](#skipping-tests) will be skipped regardless of whether a **Permissive** or **Hardened** profile is selected. When selecting the the permissive profile, you should see which tests were skipped by Rancher (tests that are skipped by default for RKE clusters) and which tests were skipped by a Rancher user. In the hardened test profile, the only skipped tests will be skipped by users.
|
||||
1. In the **CIS Scan Interval (cron)** job, enter a [cron expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) to define how often the cluster will be scanned.
|
||||
1. In the **CIS Scan Report Retention** field, enter the number of past reports that should be kept.
|
||||
|
||||
**Result:** The security scan will run and generate reports at the scheduled intervals.
|
||||
|
||||
The test schedule can be configured in the `cluster.yml`:
|
||||
|
||||
```yaml
|
||||
scheduled_cluster_scan:
|
||||
enabled: true
|
||||
scan_config:
|
||||
cis_scan_config:
|
||||
override_benchmark_version: rke-cis-1.4
|
||||
profile: permissive
|
||||
schedule_config:
|
||||
cron_schedule: 0 0 * * *
|
||||
retention: 24
|
||||
```
|
||||
|
||||
|
||||
# Skipping Tests
|
||||
|
||||
You can define a set of tests that will be skipped by the CIS scan when the next report is generated.
|
||||
|
||||
These tests will be skipped for subsequent CIS scans, including both manually triggered and scheduled scans, and the tests will be skipped with any profile.
|
||||
|
||||
The skipped tests will be listed alongside the test profile name in the cluster configuration options when a test profile is selected for a recurring cluster scan. The skipped tests will also be shown every time a scan is triggered manually from the Rancher UI by clicking **Run Scan.** The display of skipped tests allows you to know ahead of time which tests will be run in each scan.
|
||||
|
||||
To skip tests, you will need to define them in a Kubernetes ConfigMap resource. Each skipped CIS scan test is listed in the ConfigMap alongside the version of the CIS benchmark that the test belongs to.
|
||||
|
||||
To skip tests by editing a ConfigMap resource,
|
||||
|
||||
1. Create a `security-scan` namespace.
|
||||
1. Create a ConfigMap named `security-scan-cfg`.
|
||||
1. Enter the skip information under the key `config.json` in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"skip": {
|
||||
"rke-cis-1.4": [
|
||||
"1.1.1",
|
||||
"1.2.2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above, the CIS benchmark version is specified alongside the tests to be skipped for that version.
|
||||
|
||||
**Result:** These tests will be skipped on subsequent scans that use the defined CIS Benchmark version.
|
||||
|
||||
# Setting Alerts
|
||||
|
||||
Rancher provides a set of alerts for cluster scans. which are not configured to have notifiers by default:
|
||||
|
||||
- A manual cluster scan was completed
|
||||
- A manual cluster scan has failures
|
||||
- A scheduled cluster scan was completed
|
||||
- A scheduled cluster scan has failures
|
||||
|
||||
> **Prerequisite:** You need to configure a [notifier](../explanations/integrations-in-rancher/notifiers.md) before configuring, sending, or receiving alerts.
|
||||
|
||||
To activate an existing alert for a CIS scan result,
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > Alerts.**
|
||||
1. Go to the section called **A set of alerts for cluster scans.**
|
||||
1. Go to the alert you want to activate and click **⋮ > Activate.**
|
||||
1. Go to the alert rule group **A set of alerts for cluster scans** and click **⋮ > Edit.**
|
||||
1. Scroll down to the **Alert** section. In the **To** field, select the notifier that you would like to use for sending alert notifications.
|
||||
1. Optional: To limit the frequency of the notifications, click on **Show advanced options** and configure the time interval of the alerts.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
To create a new alert,
|
||||
|
||||
1. Go to the cluster view and click **Tools > CIS Scans.**
|
||||
1. Click **Add Alert.**
|
||||
1. Fill out the form.
|
||||
1. Enter a name for the alert.
|
||||
1. In the **Is** field, set the alert to be triggered when a scan is completed or when a scan has a failure.
|
||||
1. In the **Send a** field, set the alert as a **Critical,** **Warning,** or **Info** alert level.
|
||||
1. Choose a [notifier](../explanations/integrations-in-rancher/notifiers.md) for the alert.
|
||||
|
||||
**Result:** The alert is created and activated. The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.
|
||||
|
||||
For more information about alerts, refer to [this page.](./cluster-alerts.md)
|
||||
|
||||
# Deleting a Report
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > CIS Scans.**
|
||||
1. Go to the report that should be deleted.
|
||||
1. Click the **⋮ > Delete.**
|
||||
1. Click **Delete.**
|
||||
|
||||
# Downloading a Report
|
||||
|
||||
1. From the cluster view in Rancher, click **Tools > CIS Scans.**
|
||||
1. Go to the report that you want to download. Click **⋮ > Download.**
|
||||
|
||||
**Result:** The report is downloaded in CSV format.
|
||||
|
||||
# List of Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to [this page](../explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md).
|
||||
Please refer [here](../pages-for-subheaders/cis-scan-guides.md) for how-to guides on CIS scans.
|
||||
@@ -1,83 +1,5 @@
|
||||
---
|
||||
title: Using the Rancher Command Line Interface
|
||||
description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI
|
||||
metaTitle: "Using the Rancher Command Line Interface "
|
||||
metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI"
|
||||
weight: 21
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/cluster-access/cli
|
||||
- /rancher/v2.x/en/cli/
|
||||
title: CLI with Rancher
|
||||
---
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
### Download Rancher CLI
|
||||
|
||||
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary.
|
||||
|
||||
### Requirements
|
||||
|
||||
After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:
|
||||
|
||||
- Your Rancher Server URL, which is used to connect to Rancher Server.
|
||||
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key](../reference-guides/user-settings/api-keys.md).
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `<BEARER_TOKEN>` and `<SERVER_URL>` with your information):
|
||||
|
||||
```bash
|
||||
$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>
|
||||
```
|
||||
|
||||
If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.
|
||||
|
||||
### Project Selection
|
||||
|
||||
Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
|
||||
|
||||
**Example: `./rancher context switch` Output**
|
||||
```
|
||||
User:rancher-cli-directory user$ ./rancher context switch
|
||||
NUMBER CLUSTER NAME PROJECT ID PROJECT NAME
|
||||
1 cluster-2 c-7q96s:p-h4tmb project-2
|
||||
2 cluster-2 c-7q96s:project-j6z6d Default
|
||||
3 cluster-1 c-lchzv:p-xbpdt project-1
|
||||
4 cluster-1 c-lchzv:project-s2mch Default
|
||||
Select a Project:
|
||||
```
|
||||
|
||||
After you enter a number, the console displays a message that you've changed projects.
|
||||
|
||||
```
|
||||
INFO[0005] Setting new context to project project-1
|
||||
INFO[0005] Saving config to /Users/markbishop/.rancher/cli2.json
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
The following commands are available for use in Rancher CLI.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `apps, [app]` | Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or Rancher charts. |
|
||||
| `catalog` | Performs operations on [catalogs](./helm-charts-in-rancher.md). |
|
||||
| `clusters, [cluster]` | Performs operations on your [clusters](kubernetes-clusters-in-rancher-setup.md). |
|
||||
| `context` | Switches between Rancher [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). For an example, see [Project Selection](#project-selection). |
|
||||
| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md) and [workloads](workloads-and-pods.md)). Specify resources by name or ID. |
|
||||
| `kubectl` |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). |
|
||||
| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). |
|
||||
| `namespaces, [namespace]` |Performs operations on namespaces. |
|
||||
| `nodes, [node]` |Performs operations on nodes. |
|
||||
| `projects, [project]` | Performs operations on [projects](../how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.md). |
|
||||
| `ps` | Displays [workloads](workloads-and-pods.md) in a project. |
|
||||
| `settings, [setting]` | Shows the current settings for your Rancher Server. |
|
||||
| `ssh` | Connects to one of your cluster nodes using the SSH protocol. |
|
||||
| `help, [h]` | Shows a list of commands or help for one command. |
|
||||
|
||||
|
||||
### Rancher CLI Help
|
||||
|
||||
Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands.
|
||||
|
||||
All commands accept the `--help` flag, which documents each command's usage.
|
||||
Interact with Rancher using command line interface (CLI) tools from your workstation. The following docs will describe the [Rancher CLI](../reference-guides/cli-with-rancher/rancher-cli.md) and [kubectl Utility](../reference-guides/cli-with-rancher/kubectl-utility).
|
||||
+5
-1
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
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).
|
||||
+1
-20
@@ -26,26 +26,7 @@ If no value has been set, Rancher uses the default value.
|
||||
|
||||
Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.
|
||||
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect.
|
||||
|
||||
> **Note:** As of v2.4.0, there are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.
|
||||
|
||||
The following is a list of the feature flags available in Rancher:
|
||||
|
||||
- `dashboard`: This feature enables the new experimental UI that has a new look and feel. The dashboard also leverages a new API in Rancher which allows the UI to access the default Kubernetes resources without any intervention from Rancher.
|
||||
- `istio-virtual-service-ui`: This feature enables a [UI to create, read, update, and delete Istio virtual services and destination rules](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md), which are traffic management features of Istio.
|
||||
- `proxy`: This feature enables Rancher to use a new simplified code base for the proxy, which can help enhance performance and security. The proxy feature is known to have issues with Helm deployments, which prevents any catalog applications to be deployed which includes Rancher's tools like monitoring, logging, Istio, etc.
|
||||
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.](../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.md) In other words, it enables types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
The below table shows the availability and default value for feature flags in Rancher:
|
||||
|
||||
| Feature Flag Name | Default Value | Status | Available as of | Rancher Restart Required? |
|
||||
| ----------------------------- | ------------- | ------------ | --------------- |---|
|
||||
| `dashboard` | `true` | Experimental | v2.4.0 | x |
|
||||
| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | |
|
||||
| `istio-virtual-service-ui` | `true` | GA | v2.3.2 | |
|
||||
| `proxy` | `false` | Experimental | v2.4.0 | |
|
||||
| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | |
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../reference-guides/installation-references/feature-flags.md) for more information.
|
||||
|
||||
# Enabling Features when Starting Rancher
|
||||
|
||||
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Installation References
|
||||
---
|
||||
|
||||
Please see the following reference guides for other installation resources: [Rancher Helm chart options](../reference-guides/installation-references/helm-chart-options.md), [TLS settings](../reference-guides/installation-references/tls-settings.md), and [feature flags](../reference-guides/installation-references/feature-flags.md).
|
||||
@@ -1 +1,5 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
The [overview](../getting-started/introduction/overview.md) will discuss Rancher's features, capabilities, and how it makes running Kubernetes easy. The guide to the [new Rancher Manager docs structure, Divio,](../getting-started/introduction/what-are-divio-docs?.md) will explain more about the updated look and function of our docs.
|
||||
@@ -1 +1,9 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
---
|
||||
title: New User Guides
|
||||
---
|
||||
|
||||
New user guides, also known as **tutorials**, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".
|
||||
|
||||
The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.
|
||||
|
||||
The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.
|
||||
Reference in New Issue
Block a user