public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-19 11:25:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Create Rancher v2.5 docs

Browse Source
This commit is contained in:
Catherine Luse
2020-07-13 10:33:12 -07:00
parent 549bef7fec
commit e7528fdb45
303 changed files with 27019 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/k3s/latest/en/installation/tutorials/_index.md
+5
View File
@@ -0,0 +1,5 @@
---
title: Tutorials
weight: 10000
---
content/k3s/latest/en/installation/tutorials/ha-with-external-db/_index.md
+118
View File
@@ -0,0 +1,118 @@
---
title: Setting up a High-availability K3s Kubernetes Cluster for Rancher
shortTitle: Set up K3s for Rancher
weight: 2
---
> This page is under construction.
This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#environment-for-kubernetes-installations)
For systems without direct internet access, refer to the air gap installation instructions.
> **Single-node Installation Tip:**
> In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.
>
> To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes.
>
> In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.
# Prerequisites
These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infra-for-ha-with-external-db)
# Installing Kubernetes
### 1. Install Kubernetes and Set up the K3s Server
When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier.
1. Connect to one of the Linux nodes that you have prepared to run the Rancher server.
1. On the Linux node, run this command to start the K3s server and connect it to the external datastore:
```
curl -sfL https://get.k3s.io | sh -s - server \
--datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"
```
Note: The datastore endpoint can also be passed in using the environment variable `$K3S_DATASTORE_ENDPOINT`.
1. Repeat the same command on your second K3s server node.
### 2. Confirm that K3s is Running
To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes:
```
sudo k3s kubectl get nodes
```
Then you should see two nodes with the master role:
```
ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes
NAME STATUS ROLES AGE VERSION
ip-172-31-60-194 Ready master 44m v1.17.2+k3s1
ip-172-31-63-88 Ready master 6m8s v1.17.2+k3s1
```
Then test the health of the cluster pods:
```
sudo k3s kubectl get pods --all-namespaces
```
**Result:** You have successfully set up a K3s Kubernetes cluster.
### 3. Save and Start Using the kubeconfig File
When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location.
To use this `kubeconfig` file,
1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool.
2. Copy the file at `/etc/rancher/k3s/k3s.yaml` and save it to the directory `~/.kube/config` on your local machine.
3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `k3s.yaml`:
```yml
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: [CERTIFICATE-DATA]
server: [LOAD-BALANCER-DNS]:6443 # Edit this line
name: default
contexts:
- context:
cluster: default
user: default
name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
user:
password: [PASSWORD]
username: admin
```
**Result:** You can now use `kubectl` to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`:
```
kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces
```
For more information about the `kubeconfig` file, refer to the [K3s documentation]({{<baseurl>}}/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files.
### 4. Check the Health of Your Cluster Pods
Now that you have set up the `kubeconfig` file, you can use `kubectl` to access the cluster from your local machine.
Check that all the required pods and containers are healthy are ready to continue:
```
ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system metrics-server-6d684c7b5-bw59k 1/1 Running 0 8d
kube-system local-path-provisioner-58fb86bdfd-fmkvd 1/1 Running 0 8d
kube-system coredns-d798c9dd-ljjnf 1/1 Running 0 8d
```
**Result:** You have confirmed that you can access the cluster with `kubectl` and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster.
### [Next: Install Rancher]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/helm-rancher/)
content/k3s/latest/en/installation/tutorials/infra-for-ha-with-external-db/_index.md
+71
View File
@@ -0,0 +1,71 @@
---
title: 'Set up Infrastructure for a High Availability K3s Kubernetes Cluster'
weight: 1
---
> This page is under construction.
In this section, you will provision the underlying infrastructure for your Rancher management server.
The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.
For more information about each installation option, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation)
> **Note:** These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).
To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure:
- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice.
- **An external database** to store the cluster data. We recommend MySQL.
- **A load balancer** to direct traffic to the two nodes.
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
### 1. Set up Linux Nodes
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/)
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.x/en/installation/options/ec2-node) for setting up nodes as instances in Amazon EC2.
### 2. Set up External Datastore
The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.
For a high-availability K3s installation, you will need to set a [MySQL](https://www.mysql.com/) external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore.
When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database.
For an example of one way to set up the MySQL database, refer to this [tutorial]({{<baseurl>}}/rancher/v2.x/en/installation/options/rds/) for setting up MySQL on Amazon's RDS service.
For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.]({{<baseurl>}}/k3s/latest/en/installation/datastore/)
### 3. Set up the Load Balancer
You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.
When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/#external-tls-termination)
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/options/nginx/)
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/options/nlb/)
> **Important:**
> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications.
### 4. Set up the DNS Record
Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.
Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.
You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.
For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
### [Next: Set up a Kubernetes Cluster]({{<baseurl>}}/rancher/v2.x/en/installation/resources/k8s-tutorials/ka-k3s/)
content/rancher/v2.5/en/_index.md
+12
View File
@@ -0,0 +1,12 @@
---
title: "Rancher 2.5"
shortTitle: "Rancher 2.5"
description: "Rancher adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
metaTitle: "Rancher 2.5 Docs: What is New?"
metaDescription: "Rancher 2 adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
insertOneSix: false
weight: 1
ctaBanner: 0
---
> This page is under construction.
content/rancher/v2.5/en/api/_index.md
+52
View File
@@ -0,0 +1,52 @@
---
title: API
weight: 7500
---
## How to use the API
The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it, click on your user avatar in the upper right corner. Under **API & Keys**, you can find the URL endpoint as well as create [API keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/).
## Authentication
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page]({{<baseurl>}}/rancher/v2.x/en/api/api-tokens).
## Making requests
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md).
- Every type has a Schema which describes:
- The URL to get to the collection of this type of resources
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
- Every field that filtering is allowed on
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information.
- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.
- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
## Filtering
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
## Sorting
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
## Pagination
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
content/rancher/v2.5/en/api/api-keys/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: API Keys
weight: 3
---
If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI.
An API key is also required for using Rancher CLI.
API Keys are composed of four components:
- **Endpoint:** This is the IP address and path that other applications use to send requests to the Rancher API.
- **Access Key:** The token's username.
- **Secret Key:** The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together.
- **Bearer Token:** The token username and password concatenated together. Use this string for applications that prompt you for one authentication string.
## Creating an API Key
1. Select **User Avatar** > **API & Keys** from the **User Settings** menu in the upper-right.
2. Click **Add Key**.
3. **Optional:** Enter a description for the API key and select an expiration period or a scope. We recommend setting an expiration date.
The API key won't be valid after expiration. Shorter expiration periods are more secure.
A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See [Authorized Cluster Endpoints]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) for more information.
4. Click **Create**.
**Step Result:** Your API Key is created. Your API **Endpoint**, **Access Key**, **Secret Key**, and **Bearer Token** are displayed.
Use the **Bearer Token** to authenticate with Rancher CLI.
5. Copy the information displayed to a secure location. This information is only displayed once, so if you lose your key, you'll have to make a new one.
## What's Next?
- Enter your API key information into the application that will send requests to the Rancher API.
- Learn more about the Rancher endpoints and parameters by selecting **View in API** for an object in the Rancher UI.
- API keys are used for API calls and [Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli).
## Deleting API Keys
If you need to revoke an API key, delete it. You should delete API keys:
- That may have been compromised.
- That have expired.
To delete an API, select the stale key and click **Delete**.
content/rancher/v2.5/en/api/api-tokens/_index.md
+29
View File
@@ -0,0 +1,29 @@
---
title: API Tokens
weight: 1
---
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password.
You can deactivate API tokens by deleting them or by deactivating the user account.
To delete a token,
1. Go to the list of all tokens in the Rancher API view at `https://<Rancher-Server-IP>/v3/tokens`.
1. Access the token you want to delete by its ID. For example, `https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt`
1. Click **Delete.**
Here is the complete list of tokens that are generated with `ttl=0`:
| Token | Description |
|-------|-------------|
| `kubeconfig-*` | Kubeconfig token |
| `kubectl-shell-*` | Access to `kubectl` shell in the browser |
| `agent-*` | Token for agent deployment |
| `compose-token-*` | Token for compose |
| `helm-token-*` | Token for Helm chart deployment |
| `*-pipeline*` | Pipeline token for project |
| `telemetry-*` | Telemetry token |
| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) |
content/rancher/v2.5/en/applications/_index.md
+52
View File
@@ -0,0 +1,52 @@
---
title: Applications
weight: 3000
---
Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories:
<!-- TOC -->
- [Notifiers and Alerts](#notifiers-and-alerts)
- [Logging](#logging)
- [Monitoring](#monitoring)
- [Istio](#istio)
- [OPA Gatekeeper](#opa-gatekeeper)
<!-- /TOC -->
## Notifiers and Alerts
Notifiers and alerts are two features that work together to inform you of events in the Rancher system.
[Notifiers]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/notifiers) are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.
[Alerts]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/alerts) are rules that trigger those notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.
## Logging
Logging is helpful because it allows you to:
- Capture and analyze the state of your cluster
- Look for trends in your environment
- Save your logs to a safe location outside of your cluster
- Stay informed of events like a container crashing, a pod eviction, or a node dying
- More easily debugg and troubleshoot problems
Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.
For details, refer to the [logging section.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/logging)
## Monitoring
_Available as of v2.2.0_
Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with [Prometheus](https://prometheus.io/), a leading open-source monitoring solution. For details, refer to the [monitoring section.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring)
## Istio
[Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices. For details on how to enable Istio in Rancher, refer to the [Istio section.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio)
## OPA Gatekeeper
[OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) is an open-source project that provides integration between OPA and Kubernetes to provide policy control via admission controller webhooks. For details on how to enable Gatekeeper in Rancher, refer to the [OPA Gatekeeper section.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/opa-gatekeeper)
content/rancher/v2.5/en/applications/backup-restore/_index.md
+10
View File
@@ -0,0 +1,10 @@
---
title: Back up and Restore Applications
weight: 2
---
> This page is under construction.
In this section, you'll learn how to create additional backup templates for the backup/restore application so that any Kubernetes application can be backed up and restored.
For information about how to backup and restore Rancher, refer to [this section.](../../backup-restore)
content/rancher/v2.5/en/applications/ecm/_index.md
+54
View File
@@ -0,0 +1,54 @@
---
title: Enterprise Cluster Manager
weight: 2
---
After installation, the [system administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.
## First Log In
After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.
>**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.
## Authentication
One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.
For more information how authentication works and how to configure each provider, see [Authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/).
## Authorization
Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.
For more information how authorization works and how to customize roles, see [Roles Based Access Control (RBAC)]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/).
## Pod Security Policies
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.
For more information how to create and use PSPs, see [Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
## Provisioning Drivers
Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
For more information, see [Provisioning Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/).
## Adding Kubernetes Versions into Rancher
_Available as of v2.3.0_
With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions.
The information that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata/)
Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata/).
## Enabling Experimental Features
_Available as of v2.3.0_
Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about [feature flags.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags/)
content/rancher/v2.5/en/applications/ecm/access-control/_index.md
+36
View File
@@ -0,0 +1,36 @@
---
title: Access Control
weight: 300
---
> This section is under construction.
There are many ways you can interact with Kubernetes clusters that are managed by Rancher:
- **Rancher UI**
Rancher provides an intuitive user interface for interacting with your clusters. All options available in the UI use the Rancher API. Therefore any action possible in the UI is also possible in the Rancher CLI or Rancher API.
- **kubectl**
You can use the Kubernetes command-line tool, [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/), to manage your clusters. You have two options for using kubectl:
- **Rancher kubectl shell**
Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part.
For more information, see [Accessing Clusters with kubectl Shell]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-shell).
- **Terminal remote connection**
You can also interact with your clusters by installing [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your local desktop and then copying the cluster's kubeconfig file to your local `~/.kube/config` directory.
For more information, see [Accessing Clusters with kubectl and a kubeconfig File]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubectl/#accessing-clusters-with-kubectl-and-a-kubeconfig-file).
- **Rancher CLI**
You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli/). This CLI tool can interact directly with different clusters and projects or pass them `kubectl` commands.
- **Rancher API**
Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an [API key]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/). To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on **View in API** for any Rancher UI object.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/_index.md
+98
View File
@@ -0,0 +1,98 @@
---
title: Authentication Providers
weight: 1
---
> This section is under construction.
One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters.
This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.
<!-- todomark add diagram -->
## External vs. Local Authentication
The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted.
| Auth Service | Available as of |
| ------------------------------------------------------------------------------------------------ | ---------------- |
| [Microsoft Active Directory]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/) | v2.0.0 |
| [GitHub]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/github/) | v2.0.0 |
| [Microsoft Azure AD]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/azure-ad/) | v2.0.3 |
| [FreeIPA]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/freeipa/) | v2.0.5 |
| [OpenLDAP]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap/) | v2.0.5 |
| [Microsoft AD FS]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/) | v2.0.7 |
| [PingIdentity]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ping-federate/) | v2.0.7 |
| [Keycloak]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/keycloak/) | v2.1.0 |
| [Okta]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/okta/) | v2.2.0 |
| [Google OAuth]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/google/) | v2.3.0 |
| [Shibboleth]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/shibboleth) | v2.4.0 |
<br/>
However, Rancher also provides [local authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/local/).
In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if your external authentication provider is unavailable or undergoing maintenance.
## Users and Groups
Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/).
> **Note:** Local authentication does not support creating or managing groups.
For more information, see [Users and Groups]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/user-groups/)
## Scope of Rancher Authorization
After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available:
| Access Level | Description |
|----------------------------------------------|-------------|
| Allow any valid Users | _Any_ user in the authorization service can access Rancher. We generally discourage use of this setting! |
| Allow members of Clusters, Projects, plus Authorized Users and Organizations | Any user in the authorization service and any group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any user in the authentication service or group you add to the **Authorized Users and Organizations** list may log in to Rancher. |
| Restrict access to only Authorized Users and Organizations | Only users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher. |
To set the Rancher access level for users in the authorization service, follow these steps:
1. From the **Global** view, click **Security > Authentication.**
1. Use the **Site Access** options to configure the scope of user authorization. The table above explains the access level for each option.
1. Optional: If you choose an option other than **Allow any valid Users,** you can add users to the list of authorized users and organizations by searching for them in the text field that appears.
1. Click **Save.**
**Result:** The Rancher access configuration settings are applied.
{{< saml_caveats >}}
## External Authentication Configuration and Principal Users
Configuration of external authentication requires:
- A local user assigned the administrator role, called hereafter the _local principal_.
- An external user that can authenticate with your external authentication service, called hereafter the _external principal_.
Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects.
1. Sign into Rancher as the local principal and complete configuration of external authentication.
![Sign In]({{<baseurl>}}/img/rancher/sign-in.png)
2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.
![Principal ID Sharing]({{<baseurl>}}/img/rancher/principal-ID.png)
3. After you complete configuration, Rancher automatically signs out the local principal.
![Sign Out Local Principal]({{<baseurl>}}/img/rancher/sign-out-local.png)
4. Then, Rancher automatically signs you back in as the external principal.
![Sign In External Principal]({{<baseurl>}}/img/rancher/sign-in-external.png)
5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.
![Sign In External Principal]({{<baseurl>}}/img/rancher/users-page.png)
6. The external principal and the local principal share the same access rights.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/ad/_index.md
+197
View File
@@ -0,0 +1,197 @@
---
title: Configuring Active Directory (AD)
weight: 2
---
If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.
Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the [OpenLDAP authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap) integration.
> **Note:**
>
> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
## Prerequisites
You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.
Usually a (non-admin) **Domain User** account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.
Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.
> **Using TLS?**
>
> If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
## Configuration Steps
### Open Active Directory Configuration
1. Log into the Rancher UI using the initial local `admin` account.
2. From the **Global** view, navigate to **Security** > **Authentication**
3. Select **Active Directory**. The **Configure an AD server** form will be displayed.
### Configure Active Directory Server Settings
In the section titled `1. Configure an Active Directory server`, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.
> **Note:**
>
> If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch).
**Table 1: AD Server parameters**
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the AD server |
| Port | Specify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS).|
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the AD server unreachable. |
| Service Account Username | Enter the username of an AD account with read-only access to your domain partition (see [Prerequisites](#prerequisites)). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com"). |
| Service Account Password | The password for the service account. |
| Default Login Domain | When you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field **must** be left empty. |
| User Search Base | The Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".|
---
### Configure User/Group Schema
In the section titled `2. Customize Schema` you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.
Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.
> **Note:**
>
> If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values.
#### User Schema
The table below details the parameters for the user schema section configuration.
**Table 2: User schema configuration parameters**
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. |
| User Member Attribute | The attribute containing the groups that a user is a member of. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. |
| Search Filter | This filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be <code>(&#124;(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of users will be empty. |
| User Enabled Attribute | The attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard `userAccountControl`. |
| Disabled Status Bitmask | This is the value of the `User Enabled Attribute` designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see [here](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)). |
---
#### Group Schema
The table below details the parameters for the group schema configuration.
**Table 3: Group schema configuration parameters**
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. |
| Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be <code>(&#124;(cn=group1)(cn=group2))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). |
---
### Test Authentication
Once you have completed the configuration, proceed by testing the connection to the AD server **using your AD admin account**. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin.
> **Note:**
>
> The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.
1. Enter the **username** and **password** for the AD account that should be mapped to the local principal account.
2. Click **Authenticate with Active Directory** to finalise the setup.
**Result:**
- Active Directory authentication has been enabled.
- You have been signed into Rancher as administrator using the provided AD credentials.
> **Note:**
>
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services.
## Annex: Identify Search Base and Schema using ldapsearch
In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server.
The [`ldapsearch`](http://manpages.ubuntu.com/manpages/artful/man1/ldapsearch.1.html) tool allows you to query your AD server to learn about the schema used for user and group objects.
For the purpose of the example commands provided below we will assume:
- The Active Directory server has a hostname of `ad.acme.com`
- The server is listening for unencrypted connections on port `389`
- The Active Directory domain is `acme`
- You have a valid AD account with the username `jdoe` and password `secret`
### Identify Search Base
First we will use `ldapsearch` to identify the Distinguished Name (DN) of the parent node(s) for users and groups:
```
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"
```
This command performs an LDAP search with the search base set to the domain root (`-b "dc=acme,dc=com"`) and a filter targeting the user account (`sAMAccountNam=jdoe`), returning the attributes for said user:
{{< img "/img/rancher/ldapsearch-user.png" "LDAP User">}}
Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`.
Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, ie. `OU=Groups,DC=acme,DC=com`.
### Identify User Schema
The output of the above `ldapsearch` query also allows to determine the correct values to use in the user schema configuration:
- `Object Class`: **person** [1]
- `Username Attribute`: **name** [2]
- `Login Attribute`: **sAMAccountName** [3]
- `User Member Attribute`: **memberOf** [4]
> **Note:**
>
> If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead.
We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.
### Identify Group Schema
Next, we'll query one of the groups associated with this user, in this case `CN=examplegroup,OU=Groups,DC=acme,DC=com`:
```
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
-s sub "CN=examplegroup"
```
This command will inform us on the attributes used for group objects:
{{< img "/img/rancher/ldapsearch-group.png" "LDAP Group">}}
Again, this allows us to determine the correct values to enter in the group schema configuration:
- `Object Class`: **group** [1]
- `Name Attribute`: **name** [2]
- `Group Member Mapping Attribute`: **member** [3]
- `Search Attribute`: **sAMAccountName** [4]
Looking at the value of the **member** attribute, we can see that it contains the DN of the referenced user. This corresponds to the **distinguishedName** attribute in our user object. Accordingly will have to set the value of the `Group Member User Attribute` parameter to this attribute.
In the same way, we can observe that the value in the **memberOf** attribute in the user object corresponds to the **distinguishedName** [5] of the group. We therefore need to set the value for the `Group DN Attribute` parameter to this attribute.
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/azure-ad/_index.md
+206
View File
@@ -0,0 +1,206 @@
---
title: Configuring Azure AD
weight: 5
---
_Available as of v2.0.3_
If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.
>**Note:** Azure AD integration only supports Service Provider initiated logins.
>**Prerequisite:** Have an instance of Azure AD configured.
>**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
## Azure Active Directory Configuration Outline
Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.
<a id="tip"></a>
>**Tip:** Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.
<!-- TOC -->
- [1. Register Rancher with Azure](#1-register-rancher-with-azure)
- [2. Create an Azure API Key](#2-create-an-azure-api-key)
- [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher)
- [4. Copy Azure Application Data](#4-copy-azure-application-data)
- [5. Configure Azure AD in Rancher](#5-configure-azure-ad-in-rancher)
<!-- /TOC -->
### 1. Register Rancher with Azure
Before enabling Azure AD within Rancher, you must register Rancher with Azure.
1. Log in to [Microsoft Azure](https://portal.azure.com/) as an administrative user. Configuration in future steps requires administrative access rights.
1. Use search to open the **App registrations** service.
![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)
1. Click **New registrations** and complete the **Create** form.
![New App Registration]({{<baseurl>}}/img/rancher/new-app-registration.png)
1. Enter a **Name** (something like `Rancher`).
1. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.
1. In the **Redirect URI** section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.
>**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
1. Click **Register**.
>**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
### 2. Create a new client secret
From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.
1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure.
![Open Rancher Registration]({{<baseurl>}}/img/rancher/open-rancher-app.png)
1. From the navigation pane on left, click **Certificates and Secrets**.
1. Click **New client secret**.
![Create new client secret]({{< baseurl >}}/img/rancher/select-client-secret.png)
1. Enter a **Description** (something like `Rancher`).
1. Select duration for the key from the options under **Expires**. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.
1. Click **Add** (you don't need to enter a value—it will automatically populate after you save).
<a id="secret"></a>
1. Copy the key value and save it to an [empty text file](#tip).
You'll enter this key into the Rancher UI later as your **Application Secret**.
You won't be able to access the key value again within the Azure UI.
### 3. Set Required Permissions for Rancher
Next, set API permissions for Rancher within Azure.
1. From the navigation pane on left, select **API permissions**.
![Open Required Permissions]({{<baseurl>}}/img/rancher/select-required-permissions.png)
1. Click **Add a permission**.
1. From the **Azure Active Directory Graph**, select the following **Delegated Permissions**:
![Select API Permissions]({{< baseurl >}}/img/rancher/select-required-permissions-2.png)
<br/>
<br/>
- **Access the directory as the signed-in user**
- **Read directory data**
- **Read all groups**
- **Read all users' full profiles**
- **Read all users' basic profiles**
- **Sign in and read user profile**
1. Click **Add permissions**.
1. From **API permissions**, click **Grant admin consent**. Then click **Yes**.
>**Note:** You must be signed in as an Azure administrator to successfully save your permission settings.
### 4. Add a Reply URL
To use Azure AD with Rancher you must whitelist Rancher with Azure. You can complete this whitelisting by providing Azure with a reply URL for Rancher, which is your Rancher Server URL followed with a verification path.
1. From the **Setting** blade, select **Reply URLs**.
![Azure: Enter Reply URL]({{<baseurl>}}/img/rancher/enter-azure-reply-url.png)
1. From the **Reply URLs** blade, enter the URL of your Rancher Server, appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.
>**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
1. Click **Save**.
**Result:** Your reply URL is saved.
>**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
### 5. Copy Azure Application Data
As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.
1. Obtain your Rancher **Tenant ID**.
1. Use search to open the **Azure Active Directory** service.
![Open Azure Active Directory]({{<baseurl>}}/img/rancher/search-azure-ad.png)
1. From the left navigation pane, open **Overview**.
2. Copy the **Directory ID** and paste it into your [text file](#tip).
You'll paste this value into Rancher as your **Tenant ID**.
1. Obtain your Rancher **Application ID**.
1. Use search to open **App registrations**.
![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)
1. Find the entry you created for Rancher.
1. Copy the **Application ID** and paste it to your [text file](#tip).
1. Obtain your Rancher **Graph Endpoint**, **Token Endpoint**, and **Auth Endpoint**.
1. From **App registrations**, click **Endpoints**.
![Click Endpoints]({{<baseurl>}}/img/rancher/click-endpoints.png)
2. Copy the following endpoints to your clipboard and paste them into your [text file](#tip) (these values will be your Rancher endpoint values).
- **Microsoft Graph API endpoint** (Graph Endpoint)
- **OAuth 2.0 token endpoint (v1)** (Token Endpoint)
- **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint)
>**Note:** Copy the v1 version of the endpoints
### 5. Configure Azure AD in Rancher
From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.
Enter the values that you copied to your [text file](#tip).
1. Log into Rancher. From the **Global** view, select **Security > Authentication**.
1. Select **Azure AD**.
1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data).
>**Important:** When entering your Graph Endpoint, remove the tenant ID from the URL, like below.
>
><code>http<span>s://g</span>raph.windows.net/<del>abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
The following table maps the values you copied in the Azure portal to the fields in Rancher.
| Rancher Field | Azure Value |
| ------------------ | ------------------------------------- |
| Tenant ID | Directory ID |
| Application ID | Application ID |
| Application Secret | Key Value |
| Endpoint | https://login.microsoftonline.com/ |
| Graph Endpoint | Microsoft Azure AD Graph API Endpoint |
| Token Endpoint | OAuth 2.0 Token Endpoint |
| Auth Endpoint | OAuth 2.0 Authorization Endpoint |
1. Click **Authenticate with Azure**.
**Result:** Azure Active Directory authentication is configured.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/freeipa/_index.md
+54
View File
@@ -0,0 +1,54 @@
---
title: Configuring FreeIPA
weight: 4
---
_Available as of v2.0.5_
If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.
>**Prerequisites:**
>
>- You must have a [FreeIPA Server](https://www.freeipa.org/) configured.
>- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key.
>- Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
2. From the **Global** view, select **Security > Authentication** from the main menu.
3. Select **FreeIPA**.
4. Complete the **Configure an FreeIPA server** form.
You may need to log in to your domain controller to find the information requested in the form.
>**Using TLS?**
>If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.
<br/>
<br/>
>**User Search Base vs. Group Search Base**
>
>Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.
>
>* If your users and groups are in the same search base, complete only the User Search Base.
>* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
5. If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step.
>**Search Attribute** The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
>
>The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields.
>
> * `uid`: User ID
> * `sn`: Last Name
> * `givenName`: First Name
>
> With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field.
6. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication.
**Result:**
- FreeIPA authentication is configured.
- You are signed into Rancher with your FreeIPA account (i.e., the _external principal_).
content/rancher/v2.5/en/applications/ecm/access-control/authentication/github/_index.md
+51
View File
@@ -0,0 +1,51 @@
---
title: Configuring GitHub
weight: 6
---
In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.
>**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
2. From the **Global** view, select **Security > Authentication** from the main menu.
3. Select **GitHub**.
4. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration.
>**What's an Authorization Callback URL?**
>
>The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).
>When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.
5. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher.
>**Where do I find the Client ID and Client Secret?**
>
>From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.
6. Click **Authenticate with GitHub**.
7. Use the **Site Access** options to configure the scope of user authorization.
- **Allow any valid Users**
_Any_ GitHub user can access Rancher. We generally discourage use of this setting!
- **Allow members of Clusters, Projects, plus Authorized Users and Organizations**
Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher.
- **Restrict access to only Authorized Users and Organizations**
Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.
<br/>
8. Click **Save**.
**Result:**
- GitHub authentication is configured.
- You are signed into Rancher with your GitHub account (i.e., the _external principal_).
content/rancher/v2.5/en/applications/ecm/access-control/authentication/google/_index.md
+107
View File
@@ -0,0 +1,107 @@
---
title: Configuring Google OAuth
weight: 12
---
_Available as of v2.3.0_
If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials.
Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher.
Within Rancher, only administrators or users with the **Manage Authentication** [global role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) can configure authentication.
# Prerequisites
- You must have a [G Suite admin account](https://admin.google.com) configured.
- G Suite requires a [top private domain FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL.
- You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on [this page.](https://support.google.com/a/answer/60757?hl=en)
After the Admin SDK API is enabled, your G Suite domain's API screen should look like this:
![Enable Admin APIs]({{<baseurl>}}/img/rancher/Google-Enable-APIs-Screen.png)
# Setting up G Suite for OAuth with Rancher
Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following:
1. [Add Rancher as an authorized domain in G Suite](#1-adding-rancher-as-an-authorized-domain)
1. [Generate OAuth2 credentials for the Rancher server](#2-creating-oauth2-credentials-for-the-rancher-server)
1. [Create service account credentials for the Rancher server](#3-creating-service-account-credentials)
1. [Register the service account key as an OAuth Client](#4-register-the-service-account-key-as-an-oauth-client)
### 1. Adding Rancher as an Authorized Domain
1. Click [here](https://console.developers.google.com/apis/credentials) to go to credentials page of your Google domain.
1. Select your project and click **OAuth consent screen.**
![OAuth Consent Screen]({{<baseurl>}}/img/rancher/Google-OAuth-consent-screen-tab.png)
1. Go to **Authorized Domains** and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to [this article.](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains)
1. Go to **Scopes for Google APIs** and make sure **email,** **profile** and **openid** are enabled.
**Result:** Rancher has been added as an authorized domain for the Admin SDK API.
### 2. Creating OAuth2 Credentials for the Rancher Server
1. Go to the Google API console, select your project, and go to the [credentials page.](https://console.developers.google.com/apis/credentials)
![Credentials]({{<baseurl>}}/img/rancher/Google-Credentials-tab.png)
1. On the **Create Credentials** dropdown, select **OAuth client ID.**
1. Click **Web application.**
1. Provide a name.
1. Fill out the **Authorized JavaScript origins** and **Authorized redirect URIs.** Note: The Rancher UI page for setting up Google OAuth (available from the Global view under **Security > Authentication > Google**) provides you the exact links to enter for this step.
- Under **Authorized JavaScript origins,** enter your Rancher server URL.
- Under **Authorized redirect URIs,** enter your Rancher server URL appended with the path `verify-auth`. For example, if your URI is `https://rancherServer`, you will enter `https://rancherServer/verify-auth`.
1. Click on **Create.**
1. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click **Download JSON.** Save the file so that you can provide these credentials to Rancher.
**Result:** Your OAuth credentials have been successfully created.
### 3. Creating Service Account Credentials
Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups.
Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed.
As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account.
This section describes how to:
- Create a service account
- Create a key for the service account and download the credentials as JSON
1. Click [here](https://console.developers.google.com/iam-admin/serviceaccounts) and select your project for which you generated OAuth credentials.
1. Click on **Create Service Account.**
1. Enter a name and click **Create.**
![Service account creation Step 1]({{<baseurl>}}/img/rancher/Google-svc-acc-step1.png)
1. Don't provide any roles on the **Service account permissions** page and click **Continue**
![Service account creation Step 2]({{<baseurl>}}/img/rancher/Google-svc-acc-step2.png)
1. Click on **Create Key** and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher.
![Service account creation Step 3]({{<baseurl>}}/img/rancher/Google-svc-acc-step3-key-creation.png)
**Result:** Your service account is created.
### 4. Register the Service Account Key as an OAuth Client
You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups.
Using the Unique ID of the service account key, register it as an Oauth Client using the following steps:
1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click **Unique ID** and click **OK.** This will add a **Unique ID** column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field **Key ID.**
![Service account Unique ID]({{<baseurl>}}/img/rancher/Google-Select-UniqueID-column.png)
1. Go to the [**Manage OAuth Client Access** page.](https://admin.google.com/AdminHome?chromeless=1#OGX:ManageOauthClients)
1. Add the Unique ID obtained in the previous step in the **Client Name** field.
1. In the **One or More API Scopes** field, add the following scopes:
```
openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly
```
1. Click **Authorize.**
**Result:** The service account is registered as an OAuth client in your G Suite account.
# Configuring Google OAuth in Rancher
1. Sign into Rancher using a local user assigned the [administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions) role. This user is also called the local principal.
1. From the **Global** view, click **Security > Authentication** from the main menu.
1. Click **Google.** The instructions in the UI cover the steps to set up authentication with Google OAuth.
1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
1. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
1. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
- **Step One** is about adding Rancher as an authorized domain, which we already covered in [this section.](#1-adding-rancher-as-an-authorized-domain)
- For **Step Two,** provide the OAuth credentials JSON that you downloaded after completing [this section.](#2-creating-oauth2-credentials-for-the-rancher-server) You can upload the file or paste the contents into the **OAuth Credentials** field.
- For **Step Three,** provide the service account credentials JSON that downloaded at the end of [this section.](#3-creating-service-account-credentials) The credentials will only work if you successfully [registered the service account key](#4-register-the-service-account-key-as-an-oauth-client) as an OAuth client in your G Suite account.
1. Click **Authenticate with Google**.
1. Click **Save**.
**Result:** Google authentication is successfully configured.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/keycloak/_index.md
+120
View File
@@ -0,0 +1,120 @@
---
title: Configuring 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: 7
---
_Available as of v2.1.0_
If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
## Prerequisites
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
- In Keycloak, create a [new SAML client](https://www.keycloak.org/docs/latest/server_admin/#saml-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-clients) for help.
Setting | Value
------------|------------
`Sign Documents` | `ON` <sup>1</sup>
`Sign Assertions` | `ON` <sup>1</sup>
All other `ON/OFF` Settings | `OFF`
`Client ID` | `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata`<sup>2</sup>
`Client Name` | <CLIENT_NAME> (e.g. `rancher`)
`Client Protocol` | `SAML`
`Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs`
><sup>1</sup>: Optionally, you can enable either one or both of these settings.
><sup>2</sup>: Rancher SAML metadata won't be generated until a SAML provider is configured and saved.
- Export a `metadata.xml` file from your Keycloak client:
From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file.
## Configuring Keycloak in Rancher
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **Keycloak**.
1. Complete the **Configure Keycloak Account** form. Keycloak IdP lets you specify what data store you want to use. You can either add a database or use an existing LDAP server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
| Field | Description |
| ------------------------- | ----------------------------------------------------------------------------- |
| Display Name Field | The AD attribute that contains the display name of users. |
| User Name Field | The AD attribute that contains the user name/given name. |
| UID Field | An AD attribute that is unique to every user. |
| Groups Field | Make entries for managing group memberships. |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. |
| IDP-metadata | The `metadata.xml` file that you exported from your IdP server. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
1. After you complete the **Configure Keycloak Account** form, click **Authenticate with Keycloak**, which is at the bottom of the page.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.
{{< saml_caveats >}}
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
### You are not redirected to Keycloak
When you click on **Authenticate with Keycloak**, your are not redirected to your IdP.
* Verify your Keycloak client configuration.
* Make sure `Force Post Binding` set to `OFF`.
### Forbidden message displayed after IdP login
You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a `Forbidden` message afterwards.
* Check the Rancher debug log.
* If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client.
### HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata
This is usually due to the metadata not being created until a SAML provider is configured.
Try configuring and saving keycloak as your SAML provider and then accessing the metadata.
### Keycloak Error: "We're sorry, failed to process response"
* Check your Keycloak log.
* If the log displays `failed: org.keycloak.common.VerificationException: Client does not have a public key`, set `Encrypt Assertions` to `OFF` in your Keycloak client.
### Keycloak Error: "We're sorry, invalid requester"
* Check your Keycloak log.
* If the log displays `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`, set `Client Signature Required` to `OFF` in your Keycloak client.
### Keycloak 6.0.0+: IDPSSODescriptor missing from options
Keycloak versions 6.0.0 and up no longer provide the IDP metadata under the `Installation` tab.
You can still get the XML from the following url:
`https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}/protocol/saml/descriptor`
The XML obtained from this URL contains `EntitiesDescriptor` as the root element. Rancher expects the root element to be `EntityDescriptor` rather than `EntitiesDescriptor`. So before passing this XML to Rancher, follow these steps to adjust it:
* Copy all the tags from `EntitiesDescriptor` to the `EntityDescriptor`.
* Remove the `<EntitiesDescriptor>` tag from the beginning.
* Remove the `</EntitiesDescriptor>` from the end of the xml.
You are left with something similar as the example below:
```
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
....
</EntityDescriptor>
```
content/rancher/v2.5/en/applications/ecm/access-control/authentication/local/_index.md
+14
View File
@@ -0,0 +1,14 @@
---
title: Local Authentication
weight: 1
---
Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the `admin` user that logs in to Rancher for the first time is a local user.
## Adding Local Users
Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.
1. From the **Global** view, select **Users** from the navigation bar.
2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/microsoft-adfs/_index.md
+36
View File
@@ -0,0 +1,36 @@
---
title: Configuring Microsoft Active Directory Federation Service (SAML)
weight: 9
---
_Available as of v2.0.7_
If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.
## Prerequisites
- You must have Rancher installed.
- Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the `<RANCHER_SERVER>` placeholder.
- You must have a global administrator account on your Rancher installation.
- You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured.
- Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the `<AD_SERVER>` placeholder.
- You must have access to add [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) on your AD FS Server.
## Setup Outline
Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.
- [1 — Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
- [2 — Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)
{{< saml_caveats >}}
### [Next: Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
content/rancher/v2.5/en/applications/ecm/access-control/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md
+82
View File
@@ -0,0 +1,82 @@
---
title: 1 — Configuring Microsoft AD FS for Rancher
weight: 1205
---
Before configuring Rancher to support AD FS users, you must add Rancher as a [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts) in AD FS.
1. Log into your AD server as an administrative user.
1. Open the **AD FS Management** console. Select **Add Relying Party Trust...** from the **Actions** menu and click **Start**.
{{< img "/img/rancher/adfs/adfs-overview.png" "">}}
1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party.
{{< img "/img/rancher/adfs/adfs-add-rpt-2.png" "">}}
1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`.
{{< img "/img/rancher/adfs/adfs-add-rpt-3.png" "">}}
1. Select **AD FS profile** as the configuration profile for your relying party trust.
{{< img "/img/rancher/adfs/adfs-add-rpt-4.png" "">}}
1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one.
{{< img "/img/rancher/adfs/adfs-add-rpt-5.png" "">}}
1. Select **Enable support for the SAML 2.0 WebSSO protocol**
and enter `https://<rancher-server>/v1-saml/adfs/saml/acs` for the service URL.
{{< img "/img/rancher/adfs/adfs-add-rpt-6.png" "">}}
1. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
{{< img "/img/rancher/adfs/adfs-add-rpt-7.png" "">}}
1. This tutorial will not cover multi-factor authentication; please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs) if you would like to configure multi-factor authentication.
{{< img "/img/rancher/adfs/adfs-add-rpt-8.png" "">}}
1. From **Choose Issuance Authorization RUles**, you may select either of the options available according to use case. However, for the purposes of this guide, select **Permit all users to access this relying party**.
{{< img "/img/rancher/adfs/adfs-add-rpt-9.png" "">}}
1. After reviewing your settings, select **Next** to add the relying party trust.
{{< img "/img/rancher/adfs/adfs-add-rpt-10.png" "">}}
1. Select **Open the Edit Claim Rules...** and click **Close**.
{{< img "/img/rancher/adfs/adfs-add-rpt-11.png" "">}}
1. On the **Issuance Transform Rules** tab, click **Add Rule...**.
{{< img "/img/rancher/adfs/adfs-edit-cr.png" "">}}
1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**.
{{< img "/img/rancher/adfs/adfs-add-tcr-1.png" "">}}
1. Set the **Claim rule name** to your desired name (for example, `Rancher Attributes`) and select **Active Directory** as the **Attribute store**. Create the following mapping to reflect the table below:
| LDAP Attribute | Outgoing Claim Type |
| -------------------------------------------- | ------------------- |
| Given-Name | Given Name |
| User-Principal-Name | UPN |
| Token-Groups - Qualified by Long Domain Name | Group |
| SAM-Account-Name | Name |
<br/>
{{< img "/img/rancher/adfs/adfs-add-tcr-2.png" "">}}
1. Download the `federationmetadata.xml` from your AD server at:
```
https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml
```
**Result:** You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.
### [Next: Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
content/rancher/v2.5/en/applications/ecm/access-control/authentication/microsoft-adfs/rancher-adfs-setup/_index.md
+45
View File
@@ -0,0 +1,45 @@
---
title: 2 — Configuring Rancher for Microsoft AD FS
weight: 1205
---
_Available as of v2.0.7_
After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.
>**Important Notes For Configuring Your AD FS Server:**
>
>- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
>- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
>- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **Microsoft Active Directory Federation Services**.
1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The examples below describe how you can map AD attributes to fields within Rancher.
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display Name Field | The AD attribute that contains the display name of users. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` |
| User Name Field | The AD attribute that contains the user name/given name. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| UID Field | An AD attribute that is unique to every user. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` |
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `http://schemas.xmlsoap.org/claims/Group` |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | This is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.<br/><br/>[Certificate creation command](#cert-command) |
| Metadata XML | The `federationmetadata.xml` file exported from your AD FS server. <br/><br/>You can find this file at `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`. |
<a id="cert-command"></a>
>**Tip:** You can generate a certificate using an openssl command. For example:
>
> openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
1. After you complete the **Configure AD FS Account** form, click **Authenticate with AD FS**, which is at the bottom of the page.
Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.
>**Note:** You may have to disable your popup blocker to see the AD FS login page.
**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/okta/_index.md
+53
View File
@@ -0,0 +1,53 @@
---
title: Configuring Okta (SAML)
weight: 10
---
_Available as of v2.2.0_
If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Note:** Okta integration only supports Service Provider initiated logins.
## Prerequisites
In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help.
Setting | Value
------------|------------
`Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs`
`Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata`
## Configuring Okta in Rancher
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **Okta**.
1. Complete the **Configure Okta Account** form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.
| Field | Description |
| ------------------------- | ----------------------------------------------------------------------------- |
| Display Name Field | The attribute name from an attribute statement that contains the display name of users. |
| User Name Field | The attribute name from an attribute statement that contains the user name/given name. |
| UID Field | The attribute name from an attribute statement that is unique to every user. |
| Groups Field | The attribute name in a group attribute statement that exposes your groups. |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair used for Assertion Encryption. |
| Metadata XML | The `Identity Provider metadata` file that you find in the application `Sign On` section. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt
1. After you complete the **Configure Okta Account** form, click **Authenticate with Okta**, which is at the bottom of the page.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.
>**Note:** If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.
**Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.
{{< saml_caveats >}}
content/rancher/v2.5/en/applications/ecm/access-control/authentication/openldap/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Configuring OpenLDAP
weight: 3
---
_Available as of v2.0.5_
If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.
## Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
## Configure OpenLDAP in Rancher
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](./openldap-config)
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Log into the Rancher UI using the initial local `admin` account.
2. From the **Global** view, navigate to **Security** > **Authentication**
3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
### Test Authentication
Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.
> **Note:**
>
> The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step.
1. Enter the **username** and **password** for the OpenLDAP account that should be mapped to the local principal account.
2. Click **Authenticate With OpenLDAP** to test the OpenLDAP connection and finalise the setup.
**Result:**
- OpenLDAP authentication is configured.
- The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account.
> **Note:**
>
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services.
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/openldap/openldap-config/_index.md
+86
View File
@@ -0,0 +1,86 @@
---
title: OpenLDAP Configuration Reference
weight: 2
---
This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.
For further details on configuring OpenLDAP, refer to the [official documentation.](https://www.openldap.org/doc/)
> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
- [Background: OpenLDAP Authentication Flow](#background-openldap-authentication-flow)
- [OpenLDAP server configuration](#openldap-server-configuration)
- [User/group schema configuration](#user-group-schema-configuration)
- [User schema configuration](#user-schema-configuration)
- [Group schema configuration](#group-schema-configuration)
## Background: OpenLDAP Authentication Flow
1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.
# OpenLDAP Server Configuration
You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic.
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
<figcaption>OpenLDAP Server Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the OpenLDAP server |
| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. |
| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). |
| Service Account Password | The password for the service account. |
| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|
# User/Group Schema Configuration
If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
### User Schema Configuration
The table below details the parameters for the user schema configuration.
<figcaption>User Schema Configuration Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. |
| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. |
| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
### Group Schema Configuration
The table below details the parameters for the group schema configuration.
<figcaption>Group Schema Configuration Parameters<figcaption>
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth. |
content/rancher/v2.5/en/applications/ecm/access-control/authentication/ping-federate/_index.md
+52
View File
@@ -0,0 +1,52 @@
---
title: Configuring PingIdentity (SAML)
weight: 8
---
_Available as of v2.0.7_
If your organization uses Ping Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Prerequisites:**
>
>- You must have a [Ping IdP Server](https://www.pingidentity.com/) configured.
>- Following are the Rancher Service Provider URLs needed for configuration:
Metadata URL: `https://<rancher-server>/v1-saml/ping/saml/metadata`
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/ping/saml/acs`
Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [PingIdentity documentation](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html).
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **PingIdentity**.
1. Complete the **Configure Ping Account** form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
1. **Rancher API Host**: Enter the URL for your Rancher Server.
1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
You can generate one using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
1. **IDP-metadata**: The `metadata.xml` file that you [exported from your IdP server](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html).
1. After you complete the **Configure Ping Account** form, click **Authenticate with Ping**, which is at the bottom of the page.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.
{{< saml_caveats >}}
content/rancher/v2.5/en/applications/ecm/access-control/authentication/shibboleth/_index.md
+109
View File
@@ -0,0 +1,109 @@
---
title: Configuring Shibboleth (SAML)
weight: 11
---
_Available as of v2.4.0_
If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.
In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.
If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.
> The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](./about)
This section covers the following topics:
- [Setting up Shibboleth in Rancher](#setting-up-shibboleth-in-rancher)
- [Shibboleth Prerequisites](#shibboleth-prerequisites)
- [Configure Shibboleth in Rancher](#configure-shibboleth-in-rancher)
- [SAML Provider Caveats](#saml-provider-caveats)
- [Setting up OpenLDAP in Rancher](#setting-up-openldap-in-rancher)
- [OpenLDAP Prerequisites](#openldap-prerequisites)
- [Configure OpenLDAP in Rancher](#configure-openldap-in-rancher)
- [Troubleshooting](#troubleshooting)
# Setting up Shibboleth in Rancher
### Shibboleth Prerequisites
>
>- You must have a Shibboleth IdP Server configured.
>- Following are the Rancher Service Provider URLs needed for configuration:
Metadata URL: `https://<rancher-server>/v1-saml/shibboleth/saml/metadata`
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/shibboleth/saml/acs`
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home)
### Configure Shibboleth in Rancher
If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **Shibboleth**.
1. Complete the **Configure Shibboleth Account** form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
1. **Rancher API Host**: Enter the URL for your Rancher Server.
1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
You can generate one using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
1. **IDP-metadata**: The `metadata.xml` file that you exported from your IdP server.
1. After you complete the **Configure Shibboleth Account** form, click **Authenticate with Shibboleth**, which is at the bottom of the page.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.
### SAML Provider Caveats
If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.
- There is no validation on users or groups when assigning permissions to them in Rancher.
- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.
# Setting up OpenLDAP in Rancher
If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.
### OpenLDAP Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
### Configure OpenLDAP in Rancher
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config) Note that nested group membership is not available for Shibboleth.
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Log into the Rancher UI using the initial local `admin` account.
2. From the **Global** view, navigate to **Security** > **Authentication**
3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
# Troubleshooting
If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.5/en/applications/ecm/access-control/authentication/shibboleth/about/_index.md
+34
View File
@@ -0,0 +1,34 @@
---
title: Group Permissions with Shibboleth and OpenLDAP
weight: 1
---
_Available as of Rancher v2.4_
This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.
Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.
One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.
### Terminology
- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider.
### Adding OpenLDAP Group Permissions to Rancher Resources
The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.
For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.
In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.
When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.
Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.
![Adding OpenLDAP Group Permissions to Rancher Resources]({{<baseurl>}}/img/rancher/shibboleth-with-openldap-groups.svg)
content/rancher/v2.5/en/applications/ecm/access-control/authentication/user-groups/_index.md
+64
View File
@@ -0,0 +1,64 @@
---
title: Users and Groups
weight: 1
---
Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.
Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/).
## Managing Members
When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/local/) user account, you will not be able to search for GitHub users or groups.
All users, whether they are local users or from an authentication provider, can be viewed and managed. From the **Global** view, click on **Users**.
{{< saml_caveats >}}
## User Information
Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.
Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.
### Automatically Refreshing User Information
_Available as of v2.2.0_
Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh. From the **Global** view, click on **Settings**. Two settings control this behavior:
- **`auth-user-info-max-age-seconds`**
This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to `3600` seconds, i.e. 1 hour.
- **`auth-user-info-resync-cron`**
This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *`, i.e. once a day at midnight. See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting.
> **Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.
### Manually Refreshing User Information
If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.
1. From the **Global** view, click on **Users** in the navigation bar.
1. Click on **Refresh Group Memberships**.
**Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.
>**Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.
## Session Length
_Available as of v2.3.0_
The default length (TTL) of each user session is adjustable. The default session length is 16 hours.
1. From the **Global** view, click on **Settings**.
1. In the **Settings** page, find **`auth-user-session-ttl-minutes`** and click **Edit.**
1. Enter the amount of time in minutes a session length should last and click **Save.**
**Result:** Users are automatically logged out of Rancher after the set number of minutes.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/_index.md
+28
View File
@@ -0,0 +1,28 @@
---
title: Role-Based Access Control (RBAC)
weight: 2
---
> This section is under construction.
Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/), users can either be local or external.
After you configure external authentication, the users that display on the **Users** page changes.
- If you are logged in as a local user, only local users display.
- If you are logged in as an external user, both external and local users display.
## Users and Roles
Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by _global permissions_, and _cluster and project roles_.
- [Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/):
Define user authorization outside the scope of any particular cluster.
- [Cluster and Project Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/):
Define user authorization inside the specific cluster or project where they are assigned the role.
Both global permissions and cluster and project roles are implemented on top of [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). Therefore, enforcement of permissions and roles is performed by Kubernetes.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/add-users-to-cluster/_index.md
+55
View File
@@ -0,0 +1,55 @@
---
title: Adding Users to a Cluster
weight: 1
---
> This section is under construction.
If you want to provide a user with access and permissions to _all_ projects, nodes, and resources within a cluster, assign the user a cluster membership.
>**Tip:** Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/) instead.
There are two contexts where you can add cluster members:
- Adding Members to a New Cluster
You can add members to a cluster as you create it (recommended if possible).
- [Adding Members to an Existing Cluster](#editing-cluster-membership)
You can always add members to a cluster after a cluster is provisioned.
## Editing Cluster Membership
Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.
1. From the **Global** view, open the cluster that you want to add members to.
2. From the main menu, select **Members**. Then click **Add Member**.
3. Search for the user or group that you want to add to the cluster.
If external authentication is configured:
- Rancher returns users from your [external authentication]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) source as you type.
>**Using AD but can't find your users?**
>There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/).
- A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of.
>**Note:** If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
4. Assign the user or group **Cluster** roles.
[What are Cluster Roles?]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/)
>**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment.
>
> - To add roles to the list, [Add a Custom Role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
> - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles).
**Result:** The chosen users are added to the cluster.
- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user.
- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/default-custom-roles/_index.md
+164
View File
@@ -0,0 +1,164 @@
---
title: Custom Roles
weight: 2
---
Within Rancher, _roles_ determine what actions a user can make within a cluster or project.
Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access.
This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Creating a custom role for a cluster or project](#creating-a-custom-role-for-a-cluster-or-project)
- [Creating a custom global role](#creating-a-custom-global-role)
- [Deleting a custom global role](#deleting-a-custom-global-role)
- [Assigning a custom global role to a group](#assigning-a-custom-global-role-to-a-group)
## Prerequisites
To complete the tasks on this page, one of the following permissions are required:
- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/).
- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
## Creating A Custom Role for a Cluster or Project
While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.
The steps to add custom roles differ depending on the version of Rancher.
{{% tabs %}}
{{% tab "Rancher v2.0.7+" %}}
1. From the **Global** view, select **Security > Roles** from the main menu.
1. Select a tab to determine the scope of the roles you're adding. The tabs are:
- **Cluster:** The role is valid for assignment when adding/managing members to _only_ clusters.
- **Project:** The role is valid for assignment when adding/managing members to _only_ projects.
1. Click **Add Cluster/Project Role.**
1. **Name** the role.
1. Optional: Choose the **Cluster/Project Creator Default** option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.
> Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively.
1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role.
> When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign.
1. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.
1. Click **Create**.
{{% /tab %}}
{{% tab "Rancher prior to v2.0.7" %}}
1. From the **Global** view, select **Security > Roles** from the main menu.
1. Click **Add Role**.
1. **Name** the role.
1. Choose whether to set the role to a status of [locked]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/).
> **Note:** Locked roles cannot be assigned to users.
1. In the **Context** dropdown menu, choose the scope of the role assigned to the user. The contexts are:
- **All:** The user can use their assigned role regardless of context. This role is valid for assignment when adding/managing members to clusters or projects.
- **Cluster:** This role is valid for assignment when adding/managing members to _only_ clusters.
- **Project:** This role is valid for assignment when adding/managing members to _only_ projects.
1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role.
> When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign.
1. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.
1. Click **Create**.
{{% /tab %}}
{{% /tabs %}}
## Creating a Custom Global Role
_Available as of v2.4.0_
### Creating a Custom Global Role that Copies Rules from an Existing Role
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.
The custom global role can then be assigned to a user or group so that the custom global role takes effect the first time the user or users sign into Rancher.
To create a custom global role based on an existing role,
1. Go to the **Global** view and click **Security > Roles.**
1. On the **Global** tab, go to the role that the custom global role will be based on. Click **&#8942; (…) > Clone.**
1. Enter a name for the role.
1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.**
1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role.
1. Click **Save.**
### Creating a Custom Global Role that Does Not Copy Rules from Another Role
Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:
1. Go to the **Global** view and click **Security > Roles.**
1. On the **Global** tab, click **Add Global Role.**
1. Enter a name for the role.
1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.**
1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role.
1. Click **Save.**
## Deleting a Custom Global Role
_Available as of v2.4.0_
When deleting a custom global role, all global role bindings with this custom role are deleted.
If a user is only assigned one custom global role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.
Custom global roles can be deleted, but built-in roles cannot be deleted.
To delete a custom global role,
1. Go to the **Global** view and click **Security > Roles.**
2. On the **Global** tab, go to the custom global role that should be deleted and click **&#8942; (…) > Delete.**
3. Click **Delete.**
## Assigning a Custom Global Role to a Group
_Available as of v2.4.0_
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.
When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.
If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have their individual Standard User role.
> **Prerequisites:** You can only assign a global role to a group if:
>
> * You have set up an [external authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-vs-local-authentication)
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/user-groups/)
> * You have already set up at least one user group with the authentication provider
To assign a custom global role to a group, follow these steps:
1. From the **Global** view, go to **Security > Groups.**
1. Click **Assign Global Role.**
1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role.
1. In the **Custom** section, choose any custom global role that will be assigned to the group.
1. Optional: In the **Global Permissions** or **Built-in** sections, select any additional permissions that the group should have.
1. Click **Create.**
**Result:** The custom global role will take effect when the users in the group log into Rancher.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/locked-roles/_index.md
+37
View File
@@ -0,0 +1,37 @@
---
title: Locked Roles
weight: 3
---
You can set roles to a status of `locked`. Locking roles prevent them from being assigned users in the future.
Locked roles:
- Cannot be assigned to users that don't already have it assigned.
- Are not listed in the **Member Roles** drop-down when you are adding a user to a cluster or project.
- Do not affect users assigned the role before you lock the role. These users retain access that the role provides.
**Example:** let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.
To enforce it, before you add new users to the cluster, you should lock the following roles: `Cluster Owner`, `Cluster Member`, and `Create Projects`. Then you could create a new custom role that includes the same permissions as a __Cluster Member__, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.
Roles can be locked by the following users:
- Any user assigned the `Administrator` global permission.
- Any user assigned the `Custom Users` permission, along with the `Manage Roles` role.
## Locking/Unlocking Roles
If you want to prevent a role from being assigned to users, you can set it to a status of `locked`.
You can lock roles in two contexts:
- When you're [adding a custom role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
- When you editing an existing role (see below).
1. From the **Global** view, select **Security** > **Roles**.
2. From the role that you want to lock (or unlock), select **&#8942;** > **Edit**.
3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/_index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: Access Control for the Enterprise Cluster Manager and Projects
shortTitle: Enterprise Cluster Manager
weight: 4
---
> This section is under construction.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/ace/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: How the Authorized Cluster Endpoint Works
weight: 7
---
This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for [how to set up kubectl to directly access a cluster.](../kubectl/#authenticating-directly-with-a-downstream-cluster)
### About the kubeconfig File
The _kubeconfig file_ is a file used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients).
This kubeconfig file and its contents are specific to the cluster you are viewing. It can be downloaded from the cluster view in Rancher. You will need a separate kubeconfig file for each cluster that you have access to in Rancher.
After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster.
### Two Authentication Methods for RKE Clusters
If the cluster is not an [RKE cluster,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster.
For RKE clusters, the kubeconfig file allows you to be authenticated in two ways:
- **Through the Rancher server authentication proxy:** Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access.
- **Directly with the downstream cluster's API server:** RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the `kube-api-auth` microservice) that Rancher set up.
This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.
To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](../kubectl/#authenticating-directly-with-a-downstream-cluster)
These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#communicating-with-downstream-user-clusters) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.
### About the kube-api-auth Authentication Webhook
The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the [authorized cluster endpoint,]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) which is only available for [RKE clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook.
During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens.
The scheduling rules for `kube-api-auth` are listed below:
_Applies to v2.3.0 and higher_
| Component | nodeAffinity nodeSelectorTerms | nodeSelector | Tolerations |
| -------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
| kube-api-auth | `beta.kubernetes.io/os:NotIn:windows`<br/>`node-role.kubernetes.io/controlplane:In:"true"` | none | `operator:Exists` |
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/cluster-project-roles/_index.md
+183
View File
@@ -0,0 +1,183 @@
---
title: Cluster and Project Roles
weight: 5
---
Cluster and project roles define user authorization inside a cluster or project. You can manage these roles from the **Global > Security > Roles** page.
### Membership and Role Assignment
The projects and clusters accessible to non-administrative users is determined by _membership_. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.
When you create a cluster or project, Rancher automatically assigns you as the `Owner` for it. Users assigned the `Owner` role can assign other users roles in the cluster or project.
> **Note:** Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.
### Cluster Roles
_Cluster roles_ are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: `Owner` and `Member`.
- **Cluster Owner:**
These users have full control over the cluster and all resources in it.
- **Cluster Member:**
These users can view most cluster level resources and create new projects.
#### Custom Cluster Roles
Rancher lets you assign _custom cluster roles_ to a standard user instead of the typical `Owner` or `Member` roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.
#### Cluster Role Reference
The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, `Cluster Owner` and `Cluster Member`.
| Built-in Cluster Role | Owner | Member <a id="clus-roles"></a> |
| ---------------------------------- | ------------- | --------------------------------- |
| Create Projects | ✓ | ✓ |
| Manage Cluster Backups             | ✓ | |
| Manage Cluster Catalogs | ✓ | |
| Manage Cluster Members | ✓ | |
| Manage Nodes | ✓ | |
| Manage Storage | ✓ | |
| View All Projects | ✓ | |
| View Cluster Catalogs | ✓ | ✓ |
| View Cluster Members | ✓ | ✓ |
| View Nodes | ✓ | ✓ |
For details on how each cluster role can access Kubernetes resources, you can go to the **Global** view in the Rancher UI. Then click **Security > Roles** and go to the **Clusters** tab. If you click an individual role, you can refer to the **Grant Resources** table to see all of the operations and resources that are permitted by the role.
> **Note:**
>When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
### Giving a Custom Cluster Role to a Cluster Member
After an administrator [sets up a custom cluster role,]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/#adding-a-custom-role) cluster owners and admins can then assign those roles to cluster members.
To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.
To assign the role to a new cluster member,
1. Go to the **Cluster** view, then go to the **Members** tab.
1. Click **Add Member.** Then in the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member.
1. Click **Create.**
**Result:** The member has the assigned role.
To assign any custom role to an existing cluster member,
1. Go to the member you want to give the role to. Click the **&#8942; > View in API.**
1. In the **roleTemplateId** field, go to the drop-down menu and choose the role you want to assign to the member. Click **Show Request** and **Send Request.**
**Result:** The member has the assigned role.
### Project Roles
_Project roles_ are roles that can be used to grant users access to a project. There are three primary project roles: `Owner`, `Member`, and `Read Only`.
- **Project Owner:**
These users have full control over the project and all resources in it.
- **Project Member:**
These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.
- **Read Only:**
These users can view everything in the project but cannot create, update, or delete anything.
>**Caveat:**
>
>Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `owner` or `member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned.
#### Custom Project Roles
Rancher lets you assign _custom project roles_ to a standard user instead of the typical `Owner`, `Member`, or `Read Only` roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles.
#### Project Role Reference
The following table lists each built-in custom project role available in Rancher and whether it is also granted by the `Owner`, `Member`, or `Read Only` role.
| Built-in Project Role | Owner | Member<a id="proj-roles"><a/> | Read Only |
| ---------------------------------- | ------------- | ----------------------------- | ------------- |
| Manage Project Members | ✓ | | |
| Create Namespaces | ✓ | ✓ | |
| Manage Config Maps | ✓ | ✓ | |
| Manage Ingress | ✓ | ✓ | |
| Manage Project Catalogs | ✓ | | |
| Manage Secrets | ✓ | ✓ | |
| Manage Service Accounts | ✓ | ✓ | |
| Manage Services | ✓ | ✓ | |
| Manage Volumes | ✓ | ✓ | |
| Manage Workloads | ✓ | ✓ | |
| View Config Maps | ✓ | ✓ | ✓ |
| View Ingress | ✓ | ✓ | ✓ |
| View Project Members | ✓ | ✓ | ✓ |
| View Project Catalogs | ✓ | ✓ | ✓ |
| View Secrets | ✓ | ✓ | ✓ |
| View Service Accounts | ✓ | ✓ | ✓ |
| View Services | ✓ | ✓ | ✓ |
| View Volumes | ✓ | ✓ | ✓ |
| View Workloads | ✓ | ✓ | ✓ |
> **Notes:**
>
>- Each project role listed above, including `Owner`, `Member`, and `Read Only`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page.
>- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
>- The `Manage Project Members` role allows the project owner to manage any members of the project **and** grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually.
### Defining Custom Roles
As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.
When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource **will not** override a broader grant defined in a role that the custom role is inheriting from.
### Default Cluster and Project Roles
By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either [cluster owner](#cluster-roles) or [project owner](#project-roles). However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.
There are two methods for changing default cluster/project roles:
- **Assign Custom Roles**: Create a [custom role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles) for either your [cluster](#custom-cluster-roles) or [project](#custom-project-roles), and then set the custom role as default.
- **Assign Individual Roles**: Configure multiple [cluster](#cluster-role-reference)/[project](#project-role-reference) roles as default for assignment to the creating user.
For example, instead of assigning a role that inherits other roles (such as `cluster owner`), you can choose a mix of individual roles (such as `manage nodes` and `manage storage`).
>**Note:**
>
>- Although you can [lock]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/) a default role, the system still assigns the role to users who create a cluster/project.
>- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.
### Configuring Default Roles for Cluster and Project Creators
You can change the cluster or project role(s) that are automatically assigned to the creating user.
1. From the **Global** view, select **Security > Roles** from the main menu. Select either the **Cluster** or **Project** tab.
1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **&#8942; > Edit**.
1. Enable the role as default.
{{% accordion id="cluster" label="For Clusters" %}}
1. From **Cluster Creator Default**, choose **Yes: Default role for new cluster creation**.
1. Click **Save**.
{{% /accordion %}}
{{% accordion id="project" label="For Projects" %}}
1. From **Project Creator Default**, choose **Yes: Default role for new project creation**.
1. Click **Save**.
{{% /accordion %}}
1. If you want to remove a default role, edit the permission and select **No** from the default roles option.
**Result:** The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the **Cluster/Project Creator Default** column.
### Cluster Membership Revocation Behavior
When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster _and_ a project within the cluster, that standard user [loses their cluster roles](#clus-roles) but [retains their project roles](#proj-roles). In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:
- Access the projects they hold membership in.
- Exercise any [individual project roles](#project-role-reference) they are assigned.
If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/custom-global-roles/_index.md
+6
View File
@@ -0,0 +1,6 @@
---
title: Custom Global Roles
weight: 3
---
This page is under construction.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/global-permissions/_index.md
+174
View File
@@ -0,0 +1,174 @@
---
title: Global Permissions
weight: 4
---
_Permissions_ are individual access rights that you can assign when selecting a custom permission for a user.
Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are three default global permissions: `Administrator`, `Standard User` and `User-base`.
- **Administrator:** These users have full control over the entire Rancher system and all clusters within it.
- <a id="user"></a>**Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.
- **User-Base:** User-Base users have login-access only.
You cannot update or delete the built-in Global Permissions.
This section covers the following topics:
- [Global permission assignment](#global-permission-assignment)
- [Global permissions for new local users](#global-permissions-for-new-local-users)
- [Global permissions for users with external authentication](#global-permissions-for-users-with-external-authentication)
- [Custom global permissions](#custom-global-permissions)
- [Custom global permissions reference](#custom-global-permissions-reference)
- [Configuring default global permissions for new users](#configuring-default-global-permissions)
- [Configuring global permissions for existing individual users](#configuring-global-permissions-for-existing-individual-users)
- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
- [Refreshing group memberships](#refreshing-group-memberships)
# Global Permission Assignment
Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.
### Global Permissions for New Local Users
When you create a new local user, you assign them a global permission as you complete the **Add User** form.
To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column. You can [change the default global permissions to meet your needs.](#configuring-default-global-permissions)
### Global Permissions for Users with External Authentication
When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the **New User Default** global permissions. By default, Rancher assigns the **Standard User** permission for new users.
To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column, and you can [change them to meet your needs.](#configuring-default-global-permissions)
Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users)
As of Rancher v2.4.0, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups.
# Custom Global Permissions
Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.
When a user from an [external authentication source]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default `user` permission. The standard `user` permission allows users to login and create clusters.
However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a more restrictive set of custom global permissions.
The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role.
Administrators can enforce custom global permissions in multiple ways:
- [Changing the default permissions for new users](#configuring-default-global-permissions)
- [Editing the permissions of an existing user](#configuring-global-permissions-for-individual-users)
- [Assigning a custom global permission to a group](#assigning-a-custom-global-permission-to-a-group)
### Custom Global Permissions Reference
The following table lists each custom global permission available and whether it is included in the default global permissions, `Administrator`, `Standard User` and `User-Base`.
| Custom Global Permission | Administrator | Standard User | User-Base |
| ---------------------------------- | ------------- | ------------- |-----------|
| Create Clusters | ✓ | ✓ | |
| Create RKE Templates | ✓ | ✓ | |
| Manage Authentication | ✓ | | |
| Manage Catalogs | ✓ | | |
| Manage Cluster Drivers | ✓ | | |
| Manage Node Drivers | ✓ | | |
| Manage PodSecurityPolicy Templates | ✓ | | |
| Manage Roles | ✓ | | |
| Manage Settings | ✓ | | |
| Manage Users | ✓ | | |
| Use Catalog Templates | ✓ | ✓ | |
| User Base\* (Basic log-in access) | ✓ | ✓ | |
> \*This role has two names:
>
> - When you go to the <b>Users</b> tab and edit a user's global role, this role is called <b>Login Access</b> in the custom global permissions list.
> - When you go to the <b>Security</b> tab and edit the roles from the roles page, this role is called <b>User Base.</b>
For details on which Kubernetes resources correspond to each global permission, you can go to the **Global** view in the Rancher UI. Then click **Security > Roles** and go to the **Global** tab. If you click an individual role, you can refer to the **Grant Resources** table to see all of the operations and resources that are permitted by the role.
> **Notes:**
>
> - Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`.
> - When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
### Configuring Default Global Permissions
If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.
> **Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.
To change the default global permissions that are assigned to external users upon their first log in, follow these steps:
1. From the **Global** view, select **Security > Roles** from the main menu. Make sure the **Global** tab is selected.
1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **&#8942; > Edit**.
1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**.
1. If you want to remove a default permission, edit the permission and select **No** from **New User Default**.
**Result:** The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the **New User Default** column.
### Configuring Global Permissions for Existing Individual Users
To configure permission for a user,
1. Go to the **Users** tab.
1. On this page, go to the user whose access level you want to change and click **&#8942; > Edit.**
1. In the **Global Permissions** section, click **Custom.**
1. Check the boxes for each subset of permissions you want the user to have access to.
1. Click **Save.**
> **Result:** The user's global permissions have been updated.
### Configuring Global Permissions for Groups
_Available as of v2.4.0_
If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.
After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.
For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator [refreshes the group memberships.](#refreshing-group-memberships)
For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the **New User Default** global permissions. By default, the **New User Default** permissions are equivalent to the **Standard User** global role, but the default permissions can be [configured.](#configuring-default-global-permissions)
If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default.** Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,]((#refreshing-group-memberships)) whichever comes first.
> **Prerequisites:** You can only assign a global role to a group if:
>
> * You have set up an [external authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-vs-local-authentication)
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/user-groups/)
> * You have already set up at least one user group with the authentication provider
To assign a custom global role to a group, follow these steps:
1. From the **Global** view, go to **Security > Groups.**
1. Click **Assign Global Role.**
1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role.
1. In the **Global Permissions,** **Custom,** and/or **Built-in** sections, select the permissions that the group should have.
1. Click **Create.**
**Result:** The custom global role will take effect when the users in the group log into Rancher.
### Refreshing Group Memberships
When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.
To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.
An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.
To refresh group memberships,
1. From the **Global** view, click **Security > Users.**
1. Click **Refresh Group Memberships.**
**Result:** Any changes to the group members' permissions will take effect.
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/kubectl/_index.md
+103
View File
@@ -0,0 +1,103 @@
---
title: "Access a Cluster with Kubectl and kubeconfig"
description: "Learn how you can access and manage your Kubernetes clusters using kubectl with kubectl Shell or with kubectl CLI and kubeconfig file. A kubeconfig file is used to configure access to Kubernetes. When you create a cluster with Rancher, it automatically creates a kubeconfig for your cluster."
weight: 6
---
This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.
For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/).
- [Accessing clusters with kubectl shell in the Rancher UI](#accessing-clusters-with-kubectl-shell-in-the-rancher-ui)
- [Accessing clusters with kubectl from your workstation](#accessing-clusters-with-kubectl-from-your-workstation)
- [Note on Resources created using kubectl](#note-on-resources-created-using-kubectl)
- [Authenticating Directly with a Downstream Cluster](#authenticating-directly-with-a-downstream-cluster)
- [Connecting Directly to Clusters with FQDN Defined](#connecting-directly-to-clusters-with-fqdn-defined)
- [Connecting Directly to Clusters without FQDN Defined](#connecting-directly-to-clusters-without-fqdn-defined)
### Accessing Clusters with kubectl Shell in the Rancher UI
You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.
1. From the **Global** view, open the cluster that you want to access with kubectl.
2. Click **Launch kubectl**. Use the window that opens to interact with your Kubernetes cluster.
### Accessing Clusters with kubectl from Your Workstation
This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.
This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.
> **Prerequisites:** These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
1. Log into Rancher. From the **Global** view, open the cluster that you want to access with kubectl.
1. Click **Kubeconfig File**.
1. Copy the contents displayed to your clipboard.
1. Paste the contents into a new file on your local computer. Move the file to `~/.kube/config`. Note: The default location that kubectl uses for the kubeconfig file is `~/.kube/config`, but you can use any directory and specify it using the `--kubeconfig` flag, as in this command:
```
kubectl --kubeconfig /custom/path/kube.config get pods
```
1. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.
### Note on Resources Created Using kubectl
Rancher will discover and show resources created by `kubectl`. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.
# Authenticating Directly with a Downstream Cluster
This section intended to help you set up an alternative method to access an [RKE cluster.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters)
This method is only available for RKE clusters that have the [authorized cluster endpoint]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint) enabled. When Rancher creates this RKE cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to [this page.](../ace)
We recommend that as a best practice, you should set up this method to access your RKE cluster, so that just in case you can’t connect to Rancher, you can still access the cluster.
> **Prerequisites:** The following steps assume that you have created a Kubernetes cluster and followed the steps to [connect to your cluster with kubectl from your workstation.](#accessing-clusters-with-kubectl-from-your-workstation)
To find the name of the context(s) in your downloaded kubeconfig file, run:
```
kubectl config get-contexts --kubeconfig /custom/path/kube.config
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* my-cluster my-cluster user-46tmn
my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn
```
In this example, when you use `kubectl` with the first context, `my-cluster`, you will be authenticated through the Rancher server.
With the second context, `my-cluster-controlplane-1`, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE cluster directly.
We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below.
When `kubectl` works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy.
### Connecting Directly to Clusters with FQDN Defined
If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named `<CLUSTER_NAME>-fqdn`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context.
Assuming the kubeconfig file is located at `~/.kube/config`:
```
kubectl --context <CLUSTER_NAME>-fqdn get nodes
```
Directly referencing the location of the kubeconfig file:
```
kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-fqdn get pods
```
### Connecting Directly to Clusters without FQDN Defined
If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named `<CLUSTER_NAME>-<NODE_NAME>`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context.
Assuming the kubeconfig file is located at `~/.kube/config`:
```
kubectl --context <CLUSTER_NAME>-<NODE_NAME> get nodes
```
Directly referencing the location of the kubeconfig file:
```
kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAME> get pods
```
content/rancher/v2.5/en/applications/ecm/access-control/rbac/mcm/project-members/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Adding Users to Projects
weight: 2
---
If you want to provide a user with access and permissions to _specific_ projects and resources within a cluster, assign the user a project membership.
You can add members to a project as it is created, or add them to an existing project.
>**Tip:** Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/cluster-members/) instead.
### Adding Members to a New Project
You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the [cluster administration section.]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/)
### Adding Members to an Existing Project
Following project creation, you can add users as project members so that they can access its resources.
1. From the **Global** view, open the project that you want to add members to.
2. From the main menu, select **Members**. Then click **Add Member**.
3. Search for the user or group that you want to add to the project.
If external authentication is configured:
- Rancher returns users from your external authentication source as you type.
- A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in.
>**Note:** If you are logged in as a local user, external users do not display in your search results.
1. Assign the user or group **Project** roles.
[What are Project Roles?]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/)
>**Notes:**
>
>- Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned.
>
>- For `Custom` roles, you can modify the list of individual roles available for assignment.
>
> - To add roles to the list, [Add a Custom Role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles).
> - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/).
**Result:** The chosen users are added to the project.
- To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user.
- To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles.
content/rancher/v2.5/en/applications/ecm/backing-up-a-cluster/_index.md
+141
View File
@@ -0,0 +1,141 @@
---
title: Backing up a Cluster
weight: 7
---
In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) can be easily performed.
Rancher recommends configuring recurrent `etcd` snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.
Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.
This section covers the following topics:
- [How snapshots work](#how-snapshots-work)
- [Configuring recurring snapshots](#configuring-recurring-snapshots)
- [One-time snapshots](#one-time-snapshots)
- [Snapshot backup targets](#snapshot-backup-targets)
- [Local backup target](#local-backup-target)
- [S3 backup target](#s3-backup-target)
- [Using a custom CA certificate for S3](#using-a-custom-ca-certificate-for-s3)
- [IAM Support for storing snapshots in S3](#iam-support-for-storing-snapshots-in-s3)
- [Viewing available snapshots](#viewing-available-snapshots)
- [Safe timestamps](#safe-timestamps)
- [Enabling snapshot features for clusters created before Rancher v2.2.0](#enabling-snapshot-features-for-clusters-created-before-rancher-v2-2-0)
# How Snapshots Work
{{% tabs %}}
{{% tab "Rancher v2.4.0+" %}}
When Rancher creates a snapshot, it includes three components:
- The cluster data in etcd
- The Kubernetes version
- The cluster configuration in the form of the `cluster.yml`
Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version.
The multiple components of the snapshot allow you to select from the following options if you need to a cluster from a snapshot:
- **Restore just the etcd contents:** This restoration is similar to restoring to snapshots in Rancher prior to v2.4.0.
- **Restore etcd and Kubernetes version:** This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
- **Restore etcd, Kubernetes versions and cluster configuration:** This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.
It's always recommended to take a new snapshot before any upgrades.
{{% /tab %}}
{{% tab "Rancher prior to v2.4.0" %}}
When Rancher creates a snapshot, only the etcd data is included in the snapshot.
Because the Kubernetes version is not included in the snapshot, there is no option to restore a cluster to a different Kubernetes version.
It's always recommended to take a new snapshot before any upgrades.
{{% /tab %}}
{{% /tabs %}}
# Configuring Recurring Snapshots
Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.
By default, [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the [S3 Target](#s3-backup-target) or replicating the path on disk is advised.
During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for **Cluster Options**. Click on **Show advanced options**.
In the **Advanced Cluster Options** section, there are several options available to configure:
| Option | Description | Default Value|
| --- | ---| --- |
|[etcd Snapshot Backup Target](#snapshot-backup-targets)| Select where you want the snapshots to be saved. Options are either local or in S3 | local|
|Recurring etcd Snapshot Enabled| Enable/Disable recurring snapshots | Yes|
|[Recurring etcd Snapshot Creation Period](#snapshot-creation-period-and-retention-count) | Time in hours between recurring snapshots| 12 hours |
|[Recurring etcd Snapshot Retention Count](#snapshot-creation-period-and-retention-count)| Number of snapshots to retain| 6 |
# One-Time Snapshots
In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure.
1. In the **Global** view, navigate to the cluster that you want to take a one-time snapshot.
2. Click the **&#8942; > Snapshot Now**.
**Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target.
# Snapshot Backup Targets
Rancher supports two different backup targets:
* [Local Target](#local-backup-target)
* [S3 Target](#s3-backup-target)
### Local Backup Target
By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) in `/opt/rke/etcd-snapshots`. All recurring snapshots are taken at configured intervals. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster.
### S3 Backup Target
The `S3` backup target allows users to configure a S3 compatible backend to store the snapshots. The primary benefit of this option is that if the cluster loses all the etcd nodes, the cluster can still be restored as the snapshots are stored externally. Rancher recommends external targets like `S3` backup, however its configuration requirements do require additional effort that should be considered.
| Option | Description | Required|
|---|---|---|
|S3 Bucket Name| S3 bucket name where backups will be stored| *|
|S3 Region|S3 region for the backup bucket| |
|S3 Region Endpoint|S3 regions endpoint for the backup bucket|* |
|S3 Access Key|S3 access key with permission to access the backup bucket|*|
|S3 Secret Key|S3 secret key with permission to access the backup bucket|*|
| Custom CA Certificate | A custom certificate used to access private S3 backends _Available as of v2.2.5_ ||
### Using a custom CA certificate for S3
_Available as of v2.2.5_
The backup snapshot can be stored on a custom `S3` backup like [minio](https://min.io/). If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the `Custom CA Certificate` option to connect to the S3 backend.
### IAM Support for Storing Snapshots in S3
The `S3` backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:
- The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.
- The cluster etcd nodes must have network access to the specified S3 endpoint.
- The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket.
- The Rancher Server worker node(s) must have network access to the specified S3 endpoint.
To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)
# Viewing Available Snapshots
The list of all available snapshots for the cluster is available in the Rancher UI.
1. In the **Global** view, navigate to the cluster that you want to view snapshots.
2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
# Safe Timestamps
_Available as of v2.3.0_
As of v2.2.6, snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. As of Rancher v2.3.0, the option `safe_timestamp` is added to support compatible file names. When this flag is set to `true`, all special characters in the snapshot filename timestamp are replaced.
This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface.
# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0
If you have any Rancher launched Kubernetes clusters that were created prior to v2.2.0, after upgrading Rancher, you must [edit the cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots prior to v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
content/rancher/v2.5/en/applications/ecm/cloning-clusters/_index.md
+99
View File
@@ -0,0 +1,99 @@
---
title: Cloning Clusters
weight: 18
---
If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster.
Duplication of imported clusters is not supported.
| Cluster Type | Cloneable? |
|----------------------------------|---------------|
| [Nodes Hosted by Infrastructure Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) | ✓ |
| [Hosted Kubernetes Providers]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) | ✓ |
| [Custom Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes) | ✓ |
| [Imported Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) | |
> **Warning:** During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, _not_ wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure.
## Prerequisites
Download and install [Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli). Remember to [create an API bearer token]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys) if necessary.
## 1. Export Cluster Config
Begin by using Rancher CLI to export the configuration for the cluster that you want to clone.
1. Open Terminal and change your directory to the location of the Rancher CLI binary, `rancher`.
1. Enter the following command to list the clusters managed by Rancher.
./rancher cluster ls
1. Find the cluster that you want to clone, and copy either its resource `ID` or `NAME` to your clipboard. From this point on, we'll refer to the resource `ID` or `NAME` as `<RESOURCE_ID>`, which is used as a placeholder in the next step.
1. Enter the following command to export the configuration for your cluster.
./rancher clusters export <RESOURCE_ID>
**Step Result:** The YAML for a cloned cluster prints to Terminal.
1. Copy the YAML to your clipboard and paste it in a new file. Save the file as `cluster-template.yml` (or any other name, as long as it has a `.yml` extension).
## 2. Modify Cluster Config
Use your favorite text editor to modify the cluster configuration in `cluster-template.yml` for your cloned cluster.
> **Note:** As of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
1. Open `cluster-template.yml` (or whatever you named your config) in your favorite text editor.
>**Warning:** Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.
1. As depicted in the example below, at the `<CLUSTER_NAME>` placeholder, replace your original cluster's name with a unique name (`<CLUSTER_NAME>`). If your cloned cluster has a duplicate name, the cluster will not provision successfully.
```yml
Version: v3
clusters:
<CLUSTER_NAME>: # ENTER UNIQUE NAME
dockerRootDir: /var/lib/docker
enableNetworkPolicy: false
rancherKubernetesEngineConfig:
addonJobTimeout: 30
authentication:
strategy: x509
authorization: {}
bastionHost: {}
cloudProvider: {}
ignoreDockerVersion: true
```
1. For each `nodePools` section, replace the original nodepool name with a unique name at the `<NODEPOOL_NAME>` placeholder. If your cloned cluster has a duplicate nodepool name, the cluster will not provision successfully.
```yml
nodePools:
<NODEPOOL_NAME>:
clusterId: do
controlPlane: true
etcd: true
hostnamePrefix: mark-do
nodeTemplateId: do
quantity: 1
worker: true
```
1. When you're done, save and close the configuration.
## 3. Launch Cloned Cluster
Move `cluster-template.yml` into the same directory as the Rancher CLI binary. Then run this command:
./rancher up --file cluster-template.yml
**Result:** Your cloned cluster begins provisioning. Enter `./rancher cluster ls` to confirm. You can also log into the Rancher UI and open the **Global** view to watch your provisioning cluster's progress.
content/rancher/v2.5/en/applications/ecm/cluster-configuration/_index.md
+68
View File
@@ -0,0 +1,68 @@
---
title: RKE Cluster Configuration
weight: 6
---
After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster. To edit your cluster, open the **Global** view, make sure the **Clusters** tab is selected, and then select **&#8942; > Edit** for the cluster that you want to edit.
<sup>To Edit an Existing Cluster</sup>
![Edit Cluster]({{<baseurl>}}/img/rancher/edit-cluster.png)
The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) have **Cluster Options** available for editing.
The following table summarizes the options and settings available for each cluster type:
{{% include file="/rancher/v2.x/en/cluster-provisioning/cluster-capabilities-table" %}}
## Editing Cluster Membership
Cluster administrators can [edit the membership for a cluster,]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/cluster-members) controlling which Rancher users can access the cluster and what features they can use.
## Cluster Options
When editing clusters, clusters that are [launched using RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) feature more options than clusters that are imported or hosted by a Kubernetes provider. The headings that follow document options available only for RKE clusters.
### Updating ingress-nginx
Clusters that were created before Kubernetes 1.16 will have an `ingress-nginx` `updateStrategy` of `OnDelete`. Clusters that were created with Kubernetes 1.16 or newer will have `RollingUpdate`.
If the `updateStrategy` of `ingress-nginx` is `OnDelete`, you will need to delete these pods to get the correct version for your deployment.
# Editing Other Cluster Options
In [clusters launched by RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can edit any of the remaining options that follow.
>**Note:** These options are not available for imported clusters or hosted Kubernetes clusters.
<sup>Options for RKE Clusters</sup>
![Cluster Options]({{<baseurl>}}/img/rancher/cluster-options.png)
Option | Description |
---------|----------|
Kubernetes Version | The version of Kubernetes installed on each cluster node. For more detail, see [Upgrading Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/upgrading-kubernetes). |
Network Provider | The [container networking interface]({{<baseurl>}}/rancher/v2.x/en/faq/networking/#cni-providers) that powers networking for your cluster.<br/><br/>**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. |
Project Network Isolation | As of Rancher v2.0.7, if you're using the Canal network provider, you can choose whether to enable or disable inter-project communication. |
Nginx Ingress | If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster. |
Metrics Server Monitoring | Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal. |
Pod Security Policy Support | Enables [pod security policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down. |
Docker version on nodes | Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a [supported Docker version]({{<baseurl>}}/rancher/v2.x/en/installation/options/rke-add-on/layer-7-lb/), Rancher will stop pods from running on nodes that don't have a supported Docker version installed. |
Docker Root Directory | The directory on your cluster nodes where you've installed Docker. If you install Docker on your nodes to a non-default directory, update this path. |
Default Pod Security Policy | If you enable **Pod Security Policy Support**, use this drop-down to choose the pod security policy that's applied to the cluster. |
Cloud Provider | If you're using a cloud provider to host cluster nodes launched by RKE, enable [this option]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required. |
<br/>
# Editing Cluster as YAML
>**Note:** In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: `kube_api` and `kube_controller`.
Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.
- To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**.
- To read from an existing RKE file, click **Read from File**.
In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. For more information, see the [cluster configuration reference.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options)
![image]({{<baseurl>}}/img/rancher/cluster-options-yaml.png)
For an example of RKE config file syntax, see the [RKE documentation]({{<baseurl>}}/rke/latest/en/example-yamls/).
content/rancher/v2.5/en/applications/ecm/config-private-registry/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: Configuring a Global Default Private Registry
weight: 10
---
You might want to use a private Docker registry to share your custom base images within your organization. With a private registry, you can keep a private, consistent, and centralized source of truth for the Docker images that are used in your clusters.
There are two main ways to set up private registries in Rancher: by setting up the global default registry through the **Settings** tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.
This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed.
For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the [air gapped Docker installation]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap-single-node) or [air gapped Kubernetes installation]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap-high-availability) instructions.
If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to [pass in the registry credentials through the advanced cluster options](#provisioning-clusters-with-private-registries-that-require-credentials) every time you create a new cluster.
# Setting a Private Registry with No Credentials as the Default Registry
1. Log into Rancher and configure the default administrator password.
1. Go into the **Settings** view.
{{< img "/img/rancher/airgap/settings.png" "Settings" >}}
1. Look for the setting called `system-default-registry` and choose **Edit**.
{{< img "/img/rancher/airgap/edit-system-default-registry.png" "Edit" >}}
1. Change the value to your registry (e.g. `registry.yourdomain.com:port`). Do not prefix the registry with `http://` or `https://`.
{{< img "/img/rancher/airgap/enter-system-default-registry.png" "Save" >}}
**Result:** Rancher will use your private registry to pull system images.
# Setting a Private Registry with Credentials when Deploying a Cluster
You can follow these steps to configure a private registry when you provision a cluster with Rancher:
1. When you create a cluster through the Rancher UI, go to the **Cluster Options** section and click **Show Advanced Options.**
1. In the <b>Enable Private Registries</b> section, click **Enabled.**
1. Enter the registry URL and credentials.
1. Click **Save.**
**Result:** The new cluster will be able to pull images from the private registry.
content/rancher/v2.5/en/applications/ecm/disconnecting-nodes/_index.md
+279
View File
@@ -0,0 +1,279 @@
---
title: Disconnecting Nodes from RKE Kubernetes Clusters
description: Learn about cluster cleanup when removing nodes from your Rancher-launched Kubernetes cluster. What is removed, how to do it manually
weight: 11
---
This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes.
When you use Rancher to [launch nodes for a cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher), resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.
When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in `Active` state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again.
## What Gets Removed?
When cleaning nodes provisioned using Rancher, the following components are deleted based on the type of cluster node you're removing.
| Removed Component | [Nodes Hosted by Infrastructure Provider][1] | [Custom Nodes][2] | [Hosted Cluster][3] | [Imported Nodes][4] |
| ------------------------------------------------------------------------------ | --------------- | ----------------- | ------------------- | ------------------- |
| The Rancher deployment namespace (`cattle-system` by default) | ✓ | ✓ | ✓ | ✓ |
| `serviceAccount`, `clusterRoles`, and `clusterRoleBindings` labeled by Rancher | ✓ | ✓ | ✓ | ✓ |
| Labels, Annotations, and Finalizers | ✓ | ✓ | ✓ | ✓ |
| Rancher Deployment | ✓ | ✓ | ✓ | |
| Machines, clusters, projects, and user custom resource definitions (CRDs) | ✓ | ✓ | ✓ | |
| All resources create under the `management.cattle.io` API Group | ✓ | ✓ | ✓ | |
| All CRDs created by Rancher v2.x | ✓ | ✓ | ✓ | |
[1]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/
[2]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/
[3]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/
[4]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/
## Removing a Node from a Cluster by Rancher UI
When the node is in `Active` state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed.
**To restart a node:**
```
# using reboot
$ sudo reboot
# using shutdown
$ sudo shutdown -r now
```
## Removing Rancher Components from a Cluster Manually
When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components.
>**Warning:** The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost.
### Removing Rancher Components from Imported Clusters
For imported clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions.
After the imported cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was imported into Rancher.
{{% tabs %}}
{{% tab "By UI / API" %}}
>**Warning:** This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost.
After you initiate the removal of an [imported cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) using the Rancher UI (or API), the following events occur.
1. Rancher creates a `serviceAccount` that it uses to remove the Rancher components from the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the Rancher components.
1. Using the `serviceAccount`, Rancher schedules and runs a [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) that cleans the Rancher components off of the cluster. This job also references the `serviceAccount` and its roles as dependencies, so the job deletes them before its completion.
1. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes.
**Result:** All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted.
{{% /tab %}}
{{% tab "By Script" %}}
Rather than cleaning imported cluster nodes using the Rancher UI, you can run a script instead. This functionality is available since `v2.1.0`.
>**Prerequisite:**
>
>Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
1. Open a web browser, navigate to [GitHub](https://github.com/rancher/rancher/blob/master/cleanup/user-cluster.sh), and download `user-cluster.sh`.
1. Make the script executable by running the following command from the same directory as `user-cluster.sh`:
```
chmod +x user-cluster.sh
```
1. **Air Gap Environments Only:** Open `user-cluster.sh` and replace `yaml_url` with the URL in `user-cluster.yml`.
If you don't have an air gap environment, skip this step.
1. From the same directory, run the script and provide the `rancher/rancher-agent` image version which should be equal to the version of Rancher used to manage the cluster. (`<RANCHER_VERSION>`):
>**Tip:**
>
>Add the `-dry-run` flag to preview the script's outcome without making changes.
```
./user-cluster.sh rancher/rancher-agent:<RANCHER_VERSION>
```
**Result:** The script runs. All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted.
{{% /tab %}}
{{% /tabs %}}
### Windows Nodes
To clean up a Windows node, you can run a cleanup script located in `c:\etc\rancher`. The script deletes Kubernetes generated resources and the execution binary. It also drops the firewall rules and network settings.
To run the script, you can use this command in the PowerShell:
```
pushd c:\etc\rancher
.\cleanup.ps1
popd
```
**Result:** The node is reset and can be re-added to a Kubernetes cluster.
### Docker Containers, Images, and Volumes
Based on what role you assigned to the node, there are Kubernetes components in containers, containers belonging to overlay networking, DNS, ingress controller and Rancher agent. (and pods you created that have been scheduled to this node)
**To clean all Docker containers, images and volumes:**
```
docker rm -f $(docker ps -qa)
docker rmi -f $(docker images -q)
docker volume rm $(docker volume ls -q)
```
### Mounts
Kubernetes components and secrets leave behind mounts on the system that need to be unmounted.
Mounts |
--------|
`/var/lib/kubelet/pods/XXX` (miscellaneous mounts) |
`/var/lib/kubelet` |
`/var/lib/rancher` |
**To unmount all mounts:**
```
for mount in $(mount | grep tmpfs | grep '/var/lib/kubelet' | awk '{ print $3 }') /var/lib/kubelet /var/lib/rancher; do umount $mount; done
```
### Directories and Files
The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using `rm -rf /directory_name`.
>**Note:** Depending on the role you assigned to the node, some of the directories will or won't be present on the node.
Directories |
--------|
`/etc/ceph` |
`/etc/cni` |
`/etc/kubernetes` |
`/opt/cni` |
`/opt/rke` |
`/run/secrets/kubernetes.io` |
`/run/calico` |
`/run/flannel` |
`/var/lib/calico` |
`/var/lib/etcd` |
`/var/lib/cni` |
`/var/lib/kubelet` |
`/var/lib/rancher/rke/log` |
`/var/log/containers` |
`/var/log/kube-audit` |
`/var/log/pods` |
`/var/run/calico` |
**To clean the directories:**
```
rm -rf /etc/ceph \
/etc/cni \
/etc/kubernetes \
/opt/cni \
/opt/rke \
/run/secrets/kubernetes.io \
/run/calico \
/run/flannel \
/var/lib/calico \
/var/lib/etcd \
/var/lib/cni \
/var/lib/kubelet \
/var/lib/rancher/rke/log \
/var/log/containers \
/var/log/kube-audit \
/var/log/pods \
/var/run/calico
```
### Network Interfaces and Iptables
The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. To remove these components, a restart is recommended.
**To restart a node:**
```
# using reboot
$ sudo reboot
# using shutdown
$ sudo shutdown -r now
```
If you want to know more on (virtual) network interfaces or iptables rules, please see the specific subjects below.
### Network Interfaces
>**Note:** Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node.
Interfaces |
--------|
`flannel.1` |
`cni0` |
`tunl0` |
`caliXXXXXXXXXXX` (random interface names) |
`vethXXXXXXXX` (random interface names) |
**To list all interfaces:**
```
# Using ip
ip address show
# Using ifconfig
ifconfig -a
```
**To remove an interface:**
```
ip link delete interface_name
```
### Iptables
>**Note:** Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node.
Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state.
Chains |
--------|
`cali-failsafe-in` |
`cali-failsafe-out` |
`cali-fip-dnat` |
`cali-fip-snat` |
`cali-from-hep-forward` |
`cali-from-host-endpoint` |
`cali-from-wl-dispatch` |
`cali-fw-caliXXXXXXXXXXX` (random chain names) |
`cali-nat-outgoing` |
`cali-pri-kns.NAMESPACE` (chain per namespace) |
`cali-pro-kns.NAMESPACE` (chain per namespace) |
`cali-to-hep-forward` |
`cali-to-host-endpoint` |
`cali-to-wl-dispatch` |
`cali-tw-caliXXXXXXXXXXX` (random chain names) |
`cali-wl-to-host` |
`KUBE-EXTERNAL-SERVICES` |
`KUBE-FIREWALL` |
`KUBE-MARK-DROP` |
`KUBE-MARK-MASQ` |
`KUBE-NODEPORTS` |
`KUBE-SEP-XXXXXXXXXXXXXXXX` (random chain names) |
`KUBE-SERVICES` |
`KUBE-SVC-XXXXXXXXXXXXXXXX` (random chain names) |
**To list all iptables rules:**
```
iptables -L -t nat
iptables -L -t mangle
iptables -L
```
content/rancher/v2.5/en/applications/ecm/drivers/_index.md
+44
View File
@@ -0,0 +1,44 @@
---
title: Provisioning Drivers
weight: 12
---
Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
### Rancher Drivers
With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it.
There are two types of drivers within Rancher:
* [Cluster Drivers](#cluster-drivers)
* [Node Drivers](#node-drivers)
## Cluster Drivers
Cluster drivers are used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.
By default, Rancher has activated several hosted Kubernetes cloud providers including:
* [Amazon EKS]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/)
* [Google GKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/)
* [Azure AKS]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/)
There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:
* [Alibaba ACK]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/)
* [Huawei CCE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/)
* [Tencent]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/)
## Node Drivers
Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.
If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.
Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:
* [Amazon EC2]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/)
* [Azure]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/)
* [Digital Ocean]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/)
* [vSphere]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/)
content/rancher/v2.5/en/applications/ecm/drivers/cluster-drivers/_index.md
+44
View File
@@ -0,0 +1,44 @@
---
title: Cluster Drivers
weight: 1
---
_Available as of v2.2.0_
Cluster drivers are used to create clusters in a [hosted Kubernetes provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/), such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.
If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.
### Managing Cluster Drivers
>**Prerequisites:** To create, edit, or delete cluster drivers, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
## Activating/Deactivating Cluster Drivers
By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar.
2. From the **Drivers** page, select the **Cluster Drivers** tab.
3. Select the driver that you wish to **Activate** or **Deactivate** and select the appropriate icon.
## Adding Custom Cluster Drivers
If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create _hosted_ kubernetes clusters.
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar.
2. From the **Drivers** page select the **Cluster Drivers** tab.
3. Click **Add Cluster Driver**.
4. Complete the **Add Cluster Driver** form. Then click **Create**.
### Developing your own Cluster Driver
In order to develop cluster driver to add to Rancher, please refer to our [example](https://github.com/rancher-plugins/kontainer-engine-driver-example).
content/rancher/v2.5/en/applications/ecm/drivers/node-drivers/_index.md
+37
View File
@@ -0,0 +1,37 @@
---
title: Node Drivers
weight: 2
---
Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.
If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.
#### Managing Node Drivers
>**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
## Activating/Deactivating Node Drivers
By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar. From the **Drivers** page, select the **Node Drivers** tab. In version prior to v2.2.0, you can select **Node Drivers** directly in the navigation bar.
2. Select the driver that you wish to **Activate** or **Deactivate** and select the appropriate icon.
## Adding Custom Node Drivers
If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar. From the **Drivers** page, select the **Node Drivers** tab. In version prior to v2.2.0, you can select **Node Drivers** directly in the navigation bar.
2. Click **Add Node Driver**.
3. Complete the **Add Node Driver** form. Then click **Create**.
### Developing your own node driver
Node drivers are implemented with [Docker Machine](https://docs.docker.com/machine/).
content/rancher/v2.5/en/applications/ecm/feature-flags/_index.md
+156
View File
@@ -0,0 +1,156 @@
---
title: Enabling Experimental Features
weight: 17
---
> This page is under construction.
Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an [unsupported storage type]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/enable-not-default-storage-drivers) outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.
The features can be enabled in three ways:
- [Enable features when starting Rancher.](#enabling-features-when-starting-rancher) When installing Rancher with a CLI, you can use a feature flag to enable a feature by default.
- [Enable features from the Rancher UI](#enabling-features-with-the-rancher-ui) in Rancher v2.3.3+ by going to the **Settings** page.
- [Enable features with the Rancher API](#enabling-features-with-the-rancher-api) after installing Rancher.
Each feature has two values:
- A default value, which can be configured with a flag or environment variable from the command line
- A set value, which can be configured with the Rancher API or UI
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]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/istio-virtual-service-ui), 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.]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/enable-not-default-storage-drivers) 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 | |
# Enabling Features when Starting Rancher
When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.
> **Note:** Values set from the Rancher API will override the value passed in through the command line.
{{% tabs %}}
{{% tab "Kubernetes Install" %}}
When installing Rancher with a Helm chart, use the `--features` option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:
```
helm install rancher-latest/rancher \
--name rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
```
Note: If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
### Rendering the Helm Chart for Air Gap Installations
For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the [air gap installation documentation.]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher)
Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.
The Helm 3 command is as follows:
```
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
```
The Helm 2 command is as follows:
```
helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
```
{{% /tab %}}
{{% tab "Docker Install" %}}
When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
```
docker run -d -p 80:80 -p 443:443 \
--restart=unless-stopped \
rancher/rancher:rancher-latest \
--features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-NAME-2>=true # Available as of v2.3.0
```
{{% /tab %}}
{{% /tabs %}}
# Enabling Features with the Rancher UI
_Available as of Rancher v2.3.3_
1. Go to the **Global** view and click **Settings.**
1. Click the **Feature Flags** tab. You will see a list of experimental features.
1. To enable a feature, go to the disabled feature you want to enable and click **&#8942; > Activate.**
**Result:** The feature is enabled.
### Disabling Features with the Rancher UI
1. Go to the **Global** view and click **Settings.**
1. Click the **Feature Flags** tab. You will see a list of experimental features.
1. To disable a feature, go to the enabled feature you want to disable and click **&#8942; > Deactivate.**
**Result:** The feature is disabled.
# Enabling Features with the Rancher API
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
1. In the **Value** drop-down menu, click **True.**
1. Click **Show Request.**
1. Click **Send Request.**
1. Click **Close.**
**Result:** The feature is enabled.
### Disabling Features with the Rancher API
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
1. In the upper left corner of the screen, under **Operations,** click **Edit.**
1. In the **Value** drop-down menu, click **False.**
1. Click **Show Request.**
1. Click **Send Request.**
1. Click **Close.**
**Result:** The feature is disabled.
content/rancher/v2.5/en/applications/ecm/feature-flags/enable-not-default-storage-drivers/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: Allow Unsupported Storage Drivers
weight: 1
aliases:
- /rancher/v2.x/en/admin-settings/feature-flags/enable-not-default-storage-drivers
---
_Available as of v2.3.0_
This feature allows you to use types for storage providers and provisioners that are not enabled by default.
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/)
Environment Variable Key | Default Value | Description
---|---|---
`unsupported-storage-drivers` | `false` | This feature enables types for storage providers and provisioners that are not enabled by default.
### Types for Persistent Volume Plugins that are Enabled by Default
Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:
Name | Plugin
--------|----------
Amazon EBS Disk | `aws-ebs`
AzureFile | `azure-file`
AzureDisk | `azure-disk`
Google Persistent Disk | `gce-pd`
Longhorn | `flex-volume-longhorn`
VMware vSphere Volume | `vsphere-volume`
Local | `local`
Network File System | `nfs`
hostPath | `host-path`
### Types for StorageClass that are Enabled by Default
Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:
Name | Plugin
--------|--------
Amazon EBS Disk | `aws-ebs`
AzureFile | `azure-file`
AzureDisk | `azure-disk`
Google Persistent Disk | `gce-pd`
Longhorn | `flex-volume-longhorn`
VMware vSphere Volume | `vsphere-volume`
Local | `local`
content/rancher/v2.5/en/applications/ecm/feature-flags/istio-virtual-service-ui/_index.md
+34
View File
@@ -0,0 +1,34 @@
---
title: UI for Istio Virtual Services and Destination Rules
weight: 2
aliases:
- /rancher/v2.x/en/admin-settings/feature-flags/istio-virtual-service-ui
---
_Available as of v2.3.0_
This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup) in order to use the feature.
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.]({{<baseurl>}}/rancher/v2.x/en/installation/options/feature-flags/)
Environment Variable Key | Default Value | Status | Available as of
---|---|---|---
`istio-virtual-service-ui` |`false` | Experimental | v2.3.0
`istio-virtual-service-ui` | `true` | GA | v2.3.2
# About this Feature
A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.
When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use `kubectl` to manage traffic with Istio.
The feature enables two UI tabs: one tab for **Virtual Services** and another for **Destination Rules.**
- **Virtual services** intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/)
- **Destination rules** serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule)
To see these tabs,
1. Go to the project view in Rancher and click **Resources > Istio.**
1. You will see tabs for **Traffic Graph,** which has the Kiali network visualization integrated into the UI, and **Traffic Metrics,** which shows metrics for the success rate and request volume of traffic to your services, among other metrics. Next to these tabs, you should see the tabs for **Virtual Services** and **Destination Rules.**
content/rancher/v2.5/en/applications/ecm/globaldns/_index.md
+118
View File
@@ -0,0 +1,118 @@
---
title: Global DNS
weight: 1
---
> This page is under construction.
Rancher's Global DNS feature provides a way to program an external DNS provider to route traffic to your Kubernetes applications. Since the DNS programming supports spanning applications across different Kubernetes clusters, Global DNS is configured at a global level. An application can become highly available as it allows you to have one application run on different Kubernetes clusters. If one of your Kubernetes clusters goes down, the application would still be accessible.
> **Note:** Global DNS is only available in [Kubernetes installations]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/) with the [`local` cluster enabled]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/#import-local-cluster).
## Global DNS Providers
Prior to adding in Global DNS entries, you will need to configure access to an external provider.
The following table lists the first version of Rancher each provider debuted.
| DNS Provider | Available as of |
| --- | --- |
| [AWS Route53](https://aws.amazon.com/route53/) | v2.2.0 |
| [CloudFlare](https://www.cloudflare.com/dns/) | v2.2.0 |
| [AliDNS](https://www.alibabacloud.com/product/dns) | v2.2.0 |
## Global DNS Entries
For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or to specific projects. You must [add specific annotation labels](#adding-annotations-to-ingresses-to-program-the-external-dns) to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work.
## Permissions for Global DNS Providers/Entries
By default, only [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get `Owner` role to manage them.
## Setting up Global DNS for Applications
### Add a Global DNS Provider
1. From the **Global View**, select **Tools > Global DNS Providers**.
1. To add a provider, choose from the available provider options and configure the Global DNS Provider with necessary credentials and an optional domain.
1. (Optional) Add additional users so they could use the provider when creating Global DNS entries as well as manage the Global DNS provider.
{{% accordion id="route53" label="Route53" %}}
1. Enter a **Name** for the provider.
1. (Optional) Enter the **Root Domain** of the hosted zone on AWS Route53. If this is not provided, Rancher's Global DNS Provider will work with all hosted zones that the AWS keys can access.
1. Enter the AWS **Access Key**.
1. Enter the AWS **Secret Key**.
1. Under **Member Access**, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.
1. Click **Create**.
{{% /accordion %}}
{{% accordion id="cloudflare" label="CloudFlare" %}}
1. Enter a **Name** for the provider.
1. Enter the **Root Domain**, this field is optional, in case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access.
1. Enter the CloudFlare **API Email**.
1. Enter the CloudFlare **API Key**.
1. Under **Member Access**, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.
1. Click **Create**.
{{% /accordion %}}
{{% accordion id="alidns" label="AliDNS" %}}
1. Enter a **Name** for the provider.
1. Enter the **Root Domain**, this field is optional, in case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access.
1. Enter the **Access Key**.
1. Enter the **Secret Key**.
1. Under **Member Access**, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.
1. Click **Create**.
>**Notes:**
>
>- Alibaba Cloud SDK uses TZ data. It needs to be present on `/usr/share/zoneinfo` path of the nodes running [`local` cluster]({{<baseurl>}}/rancher/v2.x/en/installation/options/chart-options/#import-local-cluster), and it is mounted to the external DNS pods. If it is not available on the nodes, please follow the [instruction](https://www.ietf.org/timezones/tzdb-2018f/tz-link.html) to prepare it.
>- Different versions of AliDNS have different allowable TTL range, where the default TTL for a global DNS entry may not be valid. Please see the [reference](https://www.alibabacloud.com/help/doc-detail/34338.htm) before adding an AliDNS entry.
{{% /accordion %}}
### Add a Global DNS Entry
1. From the **Global View**, select **Tools > Global DNS Entries**.
1. Click on **Add DNS Entry**.
1. Enter the **FQDN** you wish to program on the external DNS.
1. Select a Global DNS **Provider** from the list.
1. Select if this DNS entry will be for a [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or for workloads in different [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). You will need to ensure that [annotations are added to any ingresses](#adding-annotations-to-ingresses-to-program-the-external-dns) for the applications that you want to target.
1. Configure the **DNS TTL** value in seconds. By default, it will be 300 seconds.
1. Under **Member Access**, search for any users that you want to have the ability to manage this Global DNS entry.
## Adding Annotations to Ingresses to program the External DNS
In order for Global DNS entries to be programmed, you will need to add a specific annotation on an ingress in your application or target project and this ingress needs to use a specific `hostname` and an annotation that should match the FQDN of the Global DNS entry.
1. For any application that you want targeted for your Global DNS entry, find an ingress associated with the application.
1. In order for the DNS to be programmed, the following requirements must be met:
* The ingress routing rule must be set to use a `hostname` that matches the FQDN of the Global DNS entry.
* The ingress must have an annotation (`rancher.io/globalDNS.hostname`) and the value of this annotation should match the FQDN of the Global DNS entry.
1. Once the ingress in your [multi-cluster application]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or in your target projects are in `active` state, the FQDN will be programmed on the external DNS against the Ingress IP addresses.
## Editing a Global DNS Provider
The [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS provider and any users added as `members` to a Global DNS provider, have _owner_ access to that provider. Any members can edit the following fields:
- Root Domain
- Access Key & Secret Key
- Members
1. From the **Global View**, select **Tools > Global DNS Providers**.
1. For the Global DNS provider that you want to edit, click the **&#8942; > Edit**.
## Editing a Global DNS Entry
The [global administrators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/), creator of the Global DNS entry and any users added as `members` to a Global DNS entry, have _owner_ access to that DNS entry. Any members can edit the following fields:
- FQDN
- Global DNS Provider
- Target Projects or Multi-Cluster App
- DNS TTL
- Members
Any users who can access the Global DNS entry can **only** add target projects that they have access to. However, users can remove **any** target project as there is no check to confirm if that user has access to the target project.
Permission checks are relaxed for removing target projects in order to support situations where the user's permissions might have changed before they were able to delete the target project. Another use case could be that the target project was removed from the cluster before being removed from a target project of the Global DNS entry.
1. From the **Global View**, select **Tools > Global DNS Entries**.
1. For the Global DNS entry that you want to edit, click the **&#8942; > Edit**.
content/rancher/v2.5/en/applications/ecm/infrastructure/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: Infrastructure Management
weight: 14
---
content/rancher/v2.5/en/applications/ecm/infrastructure/cloud-credentials/_index.md
+49
View File
@@ -0,0 +1,49 @@
---
title: Managing Cloud Credentials
weight: 3
---
When you create a cluster [hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools), [node templates]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node.
Node templates can use cloud credentials to access the credential information required to provision nodes in the infrastructure providers. The same cloud credential can be used by multiple node templates. By using a cloud credential, you do not have to re-enter access keys for the same cloud provider. Cloud credentials are stored as Kubernetes secrets.
Cloud credentials are only used by node templates if there are fields marked as `password`. The default `active` node drivers have their account access fields marked as `password`, but there may be some `inactive` node drivers, which are not using them yet. These node drivers will not use cloud credentials.
You can create cloud credentials in two contexts:
- [During creation of a node template]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) for a cluster.
- In the **User Settings**
All cloud credentials are bound to the user profile of who created it. They **cannot** be shared across users.
## Creating a Cloud Credential from User Settings
1. From your user settings, select **User Avatar > Cloud Credentials**.
1. Click **Add Cloud Credential**.
1. Enter a name for the cloud credential.
1. Select a **Cloud Credential Type** from the drop down. The values of this dropdown is based on the `active` [node drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/) in Rancher.
1. Based on the selected cloud credential type, enter the required values to authenticate with the infrastructure provider.
1. Click **Create**.
**Result:** The cloud credential is created and can immediately be used to [create node templates]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates).
## Updating a Cloud Credential
When access credentials are changed or compromised, updating a cloud credential allows you to rotate those credentials while keeping the same node template.
1. From your user settings, select **User Avatar > Cloud Credentials**.
1. Choose the cloud credential you want to edit and click the **&#8942; > Edit**.
1. Update the credential information and click **Save**.
**Result:** The cloud credential is updated with the new access credentials. All existing node templates using this cloud credential will automatically use the updated information whenever [new nodes are added]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/).
## Deleting a Cloud Credential
In order to delete cloud credentials, there must not be any node template associated with it. If you are unable to delete the cloud credential, [delete any node templates]({{<baseurl>}}/rancher/v2.x/en/user-settings/node-templates/#deleting-a-node-template) that are still associated to that cloud credential.
1. From your user settings, select **User Avatar > Cloud Credentials**.
1. You can either individually delete a cloud credential or bulk delete.
- To individually delete one, choose the cloud credential you want to edit and click the **&#8942; > Delete**.
- To bulk delete cloud credentials, select one or more cloud credentials from the list. Click **Delete**.
1. Confirm that you want to delete these cloud credentials.
content/rancher/v2.5/en/applications/ecm/infrastructure/cloud-providers/_index.md
+39
View File
@@ -0,0 +1,39 @@
---
title: Setting up Cloud Providers
weight: 4
---
A _cloud provider_ is a module in Kubernetes that provides an interface for managing nodes, load balancers, and networking routes. For more information, refer to the [official Kubernetes documentation on cloud providers.](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/)
When a cloud provider is set up in Rancher, the Rancher server can automatically provision new nodes, load balancers or persistent storage devices when launching Kubernetes definitions, if the cloud provider you're using supports such automation.
Your cluster will not provision correctly if you configure a cloud provider cluster of nodes that do not meet the prerequisites.
By default, the **Cloud Provider** option is set to `None`.
The following cloud providers can be enabled:
* Amazon
* Azure
* GCE (Google Compute Engine)
### Setting up the Amazon Cloud Provider
For details on enabling the Amazon cloud provider, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/cloud-providers/amazon)
### Setting up the Azure Cloud Provider
For details on enabling the Azure cloud provider, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/cloud-providers/azure)
### Setting up the GCE Cloud Provider
For details on enabling the Google Compute Engine cloud provider, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/cloud-providers/gce)
### Setting up a Custom Cloud Provider
The `Custom` cloud provider is available if you want to configure any [Kubernetes cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/).
For the custom cloud provider option, you can refer to the [RKE docs]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/) on how to edit the yaml file for your specific cloud provider. There are specific cloud providers that have more detailed configuration :
* [vSphere]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/vsphere/)
* [Openstack]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/openstack/)
content/rancher/v2.5/en/applications/ecm/infrastructure/cloud-providers/amazon/_index.md
+150
View File
@@ -0,0 +1,150 @@
---
title: Setting up the Amazon Cloud Provider
weight: 1
---
When using the `Amazon` cloud provider, you can leverage the following capabilities:
- **Load Balancers:** Launches an AWS Elastic Load Balancer (ELB) when choosing `Layer-4 Load Balancer` in **Port Mapping** or when launching a `Service` with `type: LoadBalancer`.
- **Persistent Volumes**: Allows you to use AWS Elastic Block Stores (EBS) for persistent volumes.
See [cloud-provider-aws README](https://github.com/kubernetes/cloud-provider-aws/blob/master/README.md) for all information regarding the Amazon cloud provider.
To set up the Amazon cloud provider,
1. [Create an IAM role and attach to the instances](#1-create-an-iam-role-and-attach-to-the-instances)
2. [Configure the ClusterID](#2-configure-the-clusterid)
### 1. Create an IAM Role and attach to the instances
All nodes added to the cluster must be able to interact with EC2 so that they can create and remove resources. You can enable this interaction by using an IAM role attached to the instance. See [Amazon documentation: Creating an IAM Role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#create-iam-role) how to create an IAM role. There are two example policies:
* The first policy is for the nodes with the `controlplane` role. These nodes have to be able to create/remove EC2 resources. The following IAM policy is an example, please remove any unneeded permissions for your use case.
* The second policy is for the nodes with the `etcd` or `worker` role. These nodes only have to be able to retrieve information from EC2.
While creating an [Amazon EC2 cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), you must fill in the **IAM Instance Profile Name** (not ARN) of the created IAM role when creating the **Node Template**.
While creating a [Custom cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes), you must manually attach the IAM role to the instance(s).
IAM Policy for nodes with the `controlplane` role:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeLaunchConfigurations",
"autoscaling:DescribeTags",
"ec2:DescribeInstances",
"ec2:DescribeRegions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVolumes",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:CreateVolume",
"ec2:ModifyInstanceAttribute",
"ec2:ModifyVolume",
"ec2:AttachVolume",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:DeleteSecurityGroup",
"ec2:DeleteVolume",
"ec2:DetachVolume",
"ec2:RevokeSecurityGroupIngress",
"ec2:DescribeVpcs",
"elasticloadbalancing:AddTags",
"elasticloadbalancing:AttachLoadBalancerToSubnets",
"elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
"elasticloadbalancing:CreateLoadBalancer",
"elasticloadbalancing:CreateLoadBalancerPolicy",
"elasticloadbalancing:CreateLoadBalancerListeners",
"elasticloadbalancing:ConfigureHealthCheck",
"elasticloadbalancing:DeleteLoadBalancer",
"elasticloadbalancing:DeleteLoadBalancerListeners",
"elasticloadbalancing:DescribeLoadBalancers",
"elasticloadbalancing:DescribeLoadBalancerAttributes",
"elasticloadbalancing:DetachLoadBalancerFromSubnets",
"elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
"elasticloadbalancing:ModifyLoadBalancerAttributes",
"elasticloadbalancing:RegisterInstancesWithLoadBalancer",
"elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
"elasticloadbalancing:AddTags",
"elasticloadbalancing:CreateListener",
"elasticloadbalancing:CreateTargetGroup",
"elasticloadbalancing:DeleteListener",
"elasticloadbalancing:DeleteTargetGroup",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:DescribeLoadBalancerPolicies",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeTargetHealth",
"elasticloadbalancing:ModifyListener",
"elasticloadbalancing:ModifyTargetGroup",
"elasticloadbalancing:RegisterTargets",
"elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
"iam:CreateServiceLinkedRole",
"kms:DescribeKey"
],
"Resource": [
"*"
]
}
]
}
```
IAM policy for nodes with the `etcd` or `worker` role:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeRegions",
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:DescribeRepositories",
"ecr:ListImages",
"ecr:BatchGetImage"
],
"Resource": "*"
}
]
}
```
### 2. Configure the ClusterID
The following resources need to tagged with a `ClusterID`:
- **Nodes**: All hosts added in Rancher.
- **Subnet**: The subnet used for your cluster.
- **Security Group**: The security group used for your cluster.
>**Note:** Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB).
When you create an [Amazon EC2 Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), the `ClusterID` is automatically configured for the created nodes. Other resources still need to be tagged manually.
Use the following tag:
**Key** = `kubernetes.io/cluster/CLUSTERID` **Value** = `owned`
`CLUSTERID` can be any string you like, as long as it is equal across all tags set.
Setting the value of the tag to `owned` tells the cluster that all resources with this tag are owned and managed by this cluster. If you share resources between clusters, you can change the tag to:
**Key** = `kubernetes.io/cluster/CLUSTERID` **Value** = `shared`.
### Using Amazon Elastic Container Registry (ECR)
The kubelet component has the ability to automatically obtain ECR credentials, when the IAM profile mentioned in [Create an IAM Role and attach to the instances](#1-create-an-iam-role-and-attach-to-the-instances) is attached to the instance(s). When using a Kubernetes version older than v1.15.0, the Amazon cloud provider needs be configured in the cluster. Starting with Kubernetes version v1.15.0, the kubelet can obtain ECR credentials without having the Amazon cloud provider configured in the cluster.
content/rancher/v2.5/en/applications/ecm/infrastructure/cloud-providers/azure/_index.md
+70
View File
@@ -0,0 +1,70 @@
---
title: Setting up the Azure Cloud Provider
weight: 2
---
When using the `Azure` cloud provider, you can leverage the following capabilities:
- **Load Balancers:** Launches an Azure Load Balancer within a specific Network Security Group.
- **Persistent Volumes:** Supports using Azure Blob disks and Azure Managed Disks with standard and premium storage accounts.
- **Network Storage:** Support Azure Files via CIFS mounts.
The following account types are not supported for Azure Subscriptions:
- Single tenant accounts (i.e. accounts with no subscriptions).
- Multi-subscription accounts.
To set up the Azure cloud provider following credentials need to be configured:
1. [Set up the Azure Tenant ID](#1-set-up-the-azure-tenant-id)
2. [Set up the Azure Client ID and Azure Client Secret](#2-set-up-the-azure-client-id-and-azure-client-secret)
3. [Configure App Registration Permissions](#3-configure-app-registration-permissions)
4. [Set up Azure Network Security Group Name](#4-set-up-azure-network-security-group-name)
### 1. Set up the Azure Tenant ID
Visit [Azure portal](https://portal.azure.com), login and go to **Azure Active Directory** and select **Properties**. Your **Directory ID** is your **Tenant ID** (tenantID).
If you want to use the Azure CLI, you can run the command `az account show` to get the information.
### 2. Set up the Azure Client ID and Azure Client Secret
Visit [Azure portal](https://portal.azure.com), login and follow the steps below to create an **App Registration** and the corresponding **Azure Client ID** (aadClientId) and **Azure Client Secret** (aadClientSecret).
1. Select **Azure Active Directory**.
1. Select **App registrations**.
1. Select **New application registration**.
1. Choose a **Name**, select `Web app / API` as **Application Type** and a **Sign-on URL** which can be anything in this case.
1. Select **Create**.
In the **App registrations** view, you should see your created App registration. The value shown in the column **APPLICATION ID** is what you need to use as **Azure Client ID**.
The next step is to generate the **Azure Client Secret**:
1. Open your created App registration.
1. In the **Settings** view, open **Keys**.
1. Enter a **Key description**, select an expiration time and select **Save**.
1. The generated value shown in the column **Value** is what you need to use as **Azure Client Secret**. This value will only be shown once.
### 3. Configure App Registration Permissions
The last thing you will need to do, is assign the appropriate permissions to your App registration.
1. Go to **More services**, search for **Subscriptions** and open it.
1. Open **Access control (IAM)**.
1. Select **Add**.
1. For **Role**, select `Contributor`.
1. For **Select**, select your created App registration name.
1. Select **Save**.
### 4. Set up Azure Network Security Group Name
A custom Azure Network Security Group (securityGroupName) is needed to allow Azure Load Balancers to work.
If you provision hosts using Rancher Machine Azure driver, you will need to edit them manually to assign them to this Network Security Group.
You should already assign custom hosts to this Network Security Group during provisioning.
Only hosts expected to be load balancer back ends need to be in this group.
content/rancher/v2.5/en/applications/ecm/infrastructure/cloud-providers/gce/_index.md
+54
View File
@@ -0,0 +1,54 @@
---
title: Setting up the Google Compute Engine Cloud Provider
weight: 3
---
In this section, you'll learn how to enable the Google Compute Engine (GCE) cloud provider for custom clusters in Rancher. A custom cluster is one in which Rancher installs Kubernetes on existing nodes.
The official Kubernetes documentation for the GCE cloud provider is [here.](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#gce)
> **Prerequisites:** The service account of `Identity and API` access on GCE needs the `Computer Admin` permission.
If you are using Calico,
1. Go to the cluster view in the Rancher UI, and click **&#8942; > Edit.**
1. Click **Edit as YAML,** and enter the following configuration:
```
rancher_kubernetes_engine_config:
cloud_provider:
name: gce
customCloudProvider: |-
[Global]
project-id=<your project ID, optional>
network-name=<your network, optional if using default network>
subnetwork-name=<your subnetwork of the above network, optional if using default network>
node-instance-prefix=<your instance group name/your instance name specific prefix, required>
node-tags=<your network tags, must patch one or some tags, required>
network:
options:
calico_cloud_provider: "gce"
plugin: "calico"
```
If you are using Canal or Flannel,
1. Go to the cluster view in the Rancher UI, and click **&#8942; > Edit.**
1. Click **Edit as YAML,** and enter the following configuration:
```
rancher_kubernetes_engine_config:
cloud_provider:
name: gce
customCloudProvider: |-
[Global]
project-id=<your project ID, optional>
network-name=<your network, optional if using default network>
subnetwork-name=<your subnetwork of the above network, optional if using default network>
node-instance-prefix=<your instance group name/your instance name specific prefix, required>
node-tags=<your network tags, must patch one or some tags, required>
services:
kube_controller:
extra_args:
configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts
```
content/rancher/v2.5/en/applications/ecm/infrastructure/node-templates/_index.md
+47
View File
@@ -0,0 +1,47 @@
---
title: Managing Node Templates
weight: 2
---
When you provision a cluster [hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools), [node templates]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node. You can create node templates in two contexts:
- While [provisioning a node pool cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools).
- At any time, from your [user settings](#creating-a-node-template-from-user-settings).
When you create a node template, it is bound to your user profile. Node templates cannot be shared among users. You can delete stale node templates that you no longer user from your user settings.
## Creating a Node Template from User Settings
1. From your user settings, select **User Avatar > Node Templates**.
1. Click **Add Template**.
1. Select one of the cloud providers available. Then follow the instructions on screen to configure the template.
**Result:** The template is configured. You can use the template later when you [provision a node pool cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools).
## Updating a Node Template
1. From your user settings, select **User Avatar > Node Templates**.
1. Choose the node template that you want to edit and click the **&#8942; > Edit**.
> **Note:** As of v2.2.0, the default `active` [node drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/) and any node driver, that has fields marked as `password`, are required to use [cloud credentials]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#cloud-credentials). If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it.
1. Edit the required information and click **Save**.
**Result:** The node template is updated. All node pools using this node template will automatically use the updated information when new nodes are added.
## Cloning Node Templates
When creating new node templates from your user settings, you can clone an existing template and quickly update its settings rather than creating a new one from scratch. Cloning templates saves you the hassle of re-entering access keys for the cloud provider.
1. From your user settings, select **User Avatar > Node Templates**.
1. Find the template you want to clone. Then select **&#8942; > Clone**.
1. Complete the rest of the form.
**Result:** The template is cloned and configured. You can use the template later when you [provision a node pool cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools).
## Deleting a Node Template
When you no longer use a node template, you can delete it from your user settings.
1. From your user settings, select **User Avatar > Node Templates**.
1. Select one or more template from the list. Then click **Delete**. Confirm the delete when prompted.
content/rancher/v2.5/en/applications/ecm/infrastructure/nodes/_index.md
+226
View File
@@ -0,0 +1,226 @@
---
title: Nodes and Node Pools
weight: 1
---
After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's **Node** tab. Depending on the [option used]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) to provision the cluster, there are different node options available.
> If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters).
This section covers the following topics:
- [Node options available for each cluster creation option](#node-options-available-for-each-cluster-creation-option)
- [Nodes hosted by an infrastructure provider](#nodes-hosted-by-an-infrastructure-provider)
- [Nodes provisioned by hosted Kubernetes providers](#nodes-provisioned-by-hosted-kubernetes-providers)
- [Imported nodes](#imported-nodes)
- [Managing and editing individual nodes](#managing-and-editing-individual-nodes)
- [Viewing a node in the Rancher API](#viewing-a-node-in-the-rancher-api)
- [Deleting a node](#deleting-a-node)
- [Scaling nodes](#scaling-nodes)
- [SSH into a node hosted by an infrastructure provider](#ssh-into-a-node-hosted-by-an-infrastructure-provider)
- [Cordoning a node](#cordoning-a-node)
- [Draining a node](#draining-a-node)
- [Aggressive and safe draining options](#aggressive-and-safe-draining-options)
- [Grace period](#grace-period)
- [Timeout](#timeout)
- [Drained and cordoned state](#drained-and-cordoned-state)
- [Labeling a node to be ignored by Rancher](#labeling-a-node-to-be-ignored-by-rancher)
# Node Options Available for Each Cluster Creation Option
The following table lists which node options are available for each [type of cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-options) in Rancher. Click the links in the **Option** column for more detailed information about each feature.
| Option | [Nodes Hosted by an Infrastructure Provider][1] | [Custom Node][2] | [Hosted Cluster][3] | [Imported Nodes][4] | Description |
| ------------------------------------------------ | ------------------------------------------------ | ---------------- | ------------------- | ------------------- | ------------------------------------------------------------------ |
| [Cordon](#cordoning-a-node) | ✓ | ✓ | ✓ | | Marks the node as unschedulable. |
| [Drain](#draining-a-node) | ✓ | ✓ | ✓ | | Marks the node as unschedulable _and_ evicts all pods. |
| [Edit](#managing-and-editing-individual-nodes) | ✓ | ✓ | ✓ | | Enter a custom name, description, label, or taints for a node. |
| [View API](#viewing-a-node-in-the-rancher-api) | ✓ | ✓ | ✓ | | View API data. |
| [Delete](#deleting-a-node) | ✓ | ✓ | | | Deletes defective nodes from the cluster. |
| [Download Keys](#ssh-into-a-node-hosted-by-an-infrastructure-provider) | ✓ | | | | Download SSH key for in order to SSH into the node. |
| [Node Scaling](#scaling-nodes) | ✓ | | | | Scale the number of nodes in the node pool up or down. |
[1]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/
[2]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/
[3]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/
[4]: {{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/
### Nodes Hosted by an Infrastructure Provider
Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are [hosted in an infrastructure provider.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/)
Clusters provisioned using [one of the node pool options]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-pools) can be scaled up or down if the node pool is edited.
A node pool can also automatically maintain the node scale that's set during the initial cluster provisioning if [node auto-replace is enabled.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-auto-replace) This scale determines the number of active nodes that Rancher maintains for the cluster.
Rancher uses [node templates]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) to replace nodes in the node pool. Each node template uses cloud provider credentials to allow Rancher to set up the node in the infrastructure provider.
### Nodes Provisioned by Hosted Kubernetes Providers
Options for managing nodes [hosted by a Kubernetes provider]({{<baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly.
### Imported Nodes
Although you can deploy workloads to an [imported cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher.
# Managing and Editing Individual Nodes
Editing a node lets you:
* Change its name
* Change its description
* Add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
* Add/Remove [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
To manage individual nodes, browse to the cluster that you want to manage and then select **Nodes** from the main menu. You can open the options menu for a node by clicking its **&#8942;** icon (**...**).
# Viewing a Node in the Rancher API
Select this option to view the node's [API endpoints]({{< baseurl >}}/rancher/v2.x/en/api/).
# Deleting a Node
Use **Delete** to remove defective nodes from the cloud provider.
When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and [node auto-replace is enabled.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-auto-replace)
>**Tip:** If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete.
# Scaling Nodes
For nodes hosted by an infrastructure provider, you can scale the number of nodes in each [node pool]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-pools) by using the scale controls. This option isn't available for other cluster types.
# SSH into a Node Hosted by an Infrastructure Provider
For [nodes hosted by an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/), you have the option of downloading its SSH key so that you can connect to it remotely from your desktop.
1. From the cluster hosted by an infrastructure provider, select **Nodes** from the main menu.
1. Find the node that you want to remote into. Select **&#8942; > Download Keys**.
**Step Result:** A ZIP file containing files used for SSH is downloaded.
1. Extract the ZIP file to any location.
1. Open Terminal. Change your location to the extracted ZIP file.
1. Enter the following command:
```
ssh -i id_rsa root@<IP_OF_HOST>
```
# Cordoning a Node
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
# Draining a Node
_Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.
- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.
- For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.
You can drain nodes that are in either a `cordoned` or `active` state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods.
However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value.
### Aggressive and Safe Draining Options
The node draining options are different based on your version of Rancher.
{{% tabs %}}
{{% tab "Rancher v2.2.x+" %}}
There are two drain modes: aggressive and safe.
- **Aggressive Mode**
In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.
- **Safe Mode**
If a node has standalone pods or ephemeral data it will be cordoned but not drained.
{{% /tab %}}
{{% tab "Rancher prior to v2.2.x" %}}
The following list describes each drain option:
- **Even if there are pods not managed by a ReplicationController, ReplicaSet, Job, DaemonSet or StatefulSet**
These types of pods won't get rescheduled to a new node, since they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. Kubernetes forces you to choose this option (which will delete/evict these pods) or drain won't proceed.
- **Even if there are DaemonSet-managed pods**
Similar to above, if you have any daemonsets, drain would proceed only if this option is selected. Even when this option is on, pods won't be deleted since they'll immediately be replaced. On startup, Rancher currently has a few daemonsets running by default in the system, so this option is turned on by default.
- **Even if there are pods using emptyDir**
If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Similar to the first option, Kubernetes expects the implementation to decide what to do with these pods. Choosing this option will delete these pods.
{{% /tab %}}
{{% /tabs %}}
### Grace Period
The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.
### Timeout
The amount of time drain should continue to wait before giving up.
>**Kubernetes Known Issue:** The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was not enforced while draining a node prior to Kubernetes 1.12.
### Drained and Cordoned State
If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.
If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to `cordoned`.
Once drain successfully completes, the node will be in a state of `drained`. You can then power off or delete the node.
>**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#maintenance-on-a-node).
# Labeling a Node to be Ignored by Rancher
_Available as of 2.3.3_
Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.
In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.
You can label nodes to be ignored by using a setting in the Rancher UI, or by using `kubectl`.
> **Note:** There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state.
### Labeling Nodes to be Ignored with the Rancher UI
To add a node that is ignored by Rancher,
1. From the **Global** view, click the **Settings** tab.
1. Go to the `ignore-node-name` setting and click **&#8942; > Edit.**
1. Enter a name that Rancher will use to ignore nodes. All nodes with this name will be ignored.
1. Click **Save.**
**Result:** Rancher will not wait to register nodes with this name. In the UI, the node will displayed with a grayed-out status. The node is still part of the cluster and can be listed with `kubectl`.
If the setting is changed afterward, the ignored nodes will continue to be hidden.
### Labeling Nodes to be Ignored with kubectl
To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label:
```
cattle.rancher.io/node-status: ignore
```
**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`.
If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.
If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings under `ignore-node-name`.
content/rancher/v2.5/en/applications/ecm/k8s-metadata/_index.md
+89
View File
@@ -0,0 +1,89 @@
---
title: Upgrading Kubernetes without Upgrading Rancher
weight: 13
---
The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.
> **Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates.** Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions.
This table below describes the CRDs that are affected by the periodic data sync.
> **Note:** Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.
| Resource | Description | Rancher API URL |
|----------|-------------|-----------------|
| System Images | List of system images used to deploy Kubernetes through RKE. | `<RANCHER_SERVER_URL>/v3/rkek8ssystemimages` |
| Service Options | Default options passed to Kubernetes components like `kube-api`, `scheduler`, `kubelet`, `kube-proxy`, and `kube-controller-manager` | `<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions` |
| Addon Templates | YAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, `metrics-server`, `nginx-ingress` | `<RANCHER_SERVER_URL>/v3/rkeaddons` |
Administrators might configure the RKE metadata settings to do the following:
- Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher
- Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
- Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher
### Refresh Kubernetes Metadata
The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available under **Tools > Drivers > Refresh Kubernetes Metadata** on the right side corner.
### Configuring the Metadata Synchronization
> Only administrators can change these settings.
The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`.
The way that the metadata is configured depends on the Rancher version.
{{% tabs %}}
{{% tab "Rancher v2.4+" %}}
To edit the metadata config in Rancher,
1. Go to the **Global** view and click the **Settings** tab.
1. Go to the **rke-metadata-config** section. Click the **&#8942;** and click **Edit.**
1. You can optionally fill in the following parameters:
- `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0.
- `url`: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is `https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json`.
If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json)
However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.
{{% /tab %}}
{{% tab "Rancher v2.3" %}}
To edit the metadata config in Rancher,
1. Go to the **Global** view and click the **Settings** tab.
1. Go to the **rke-metadata-config** section. Click the **&#8942;** and click **Edit.**
1. You can optionally fill in the following parameters:
- `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0.
- `url`: This is the HTTP path that Rancher fetches data from.
- `branch`: This refers to the Git branch name if the URL is a Git URL.
If you don't have an air gap setup, you don't need to specify the URL or Git branch where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata.git)
However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL and Git branch in the `rke-metadata-config` settings to point to the new location of the repository.
{{% /tab %}}
{{% /tabs %}}
### Air Gap Setups
Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)
If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.
To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the `rke-metadata-config` settings to point to the mirror. For details, refer to [Configuring the Metadata Synchronization.](#configuring-the-metadata-synchronization)
After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.
1. To download the system images for the private registry, click the Rancher server version at the bottom left corner of the Rancher UI.
1. Download the OS specific image lists for Linux or Windows.
1. Download `rancher-images.txt`.
1. Prepare the private registry using the same steps during the [air gap install]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap/populate-private-registry), but instead of using the `rancher-images.txt` from the releases page, use the one obtained from the previous steps.
**Result:** The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.
content/rancher/v2.5/en/applications/ecm/pod-security-policies-in-projects/_index.md
+31
View File
@@ -0,0 +1,31 @@
---
title: Pod Security Policies in Projects
weight: 5600
---
> These cluster options are only available for [clusters in which Rancher has launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.
### Prerequisites
- Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
- Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [Existing Cluster: Adding a Pod Security Policy]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/#adding-changing-a-pod-security-policy).
### Applying a Pod Security Policy
1. From the **Global** view, find the cluster containing the project you want to apply a PSP to.
1. From the main menu, select **Projects/Namespaces**.
1. Find the project that you want to add a PSP to. From that project, select **&#8942; > Edit**.
1. From the **Pod Security Policy** drop-down, select the PSP you want to apply to the project.
Assigning a PSP to a project will:
- Override the cluster's default PSP.
- Apply the PSP to the project.
- Apply the PSP to any namespaces you add to the project later.
1. Click **Save**.
**Result:** The PSP is applied to the project and any namespaces added to the project.
>**Note:** Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
content/rancher/v2.5/en/applications/ecm/pod-security-policies/_index.md
+84
View File
@@ -0,0 +1,84 @@
---
title: Adding a Pod Security Policy
weight: 5
---
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges). If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of `Pod <NAME> is forbidden: unable to validate...`.
> **Note:** Assigning Pod Security Policies are only available for clusters that are [launched using RKE.]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/)
- You can assign PSPs at the cluster or project level.
- PSPs work through inheritance.
- By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
- **Exception:** Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
- You can override the default PSP by assigning a different PSP directly to the project.
- Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
>**Note:** You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by [editing the cluster.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/)
Read more about Pod Security Policies in the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
>**Best Practice:** Set pod security at the cluster level.
Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.
## Default Pod Security Policies
_Available as of v2.0.7_
Rancher ships with two default Pod Security Policies (PSPs): the `restricted` and `unrestricted` policies.
- `restricted`
This policy is based on the Kubernetes [example restricted policy](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml). It significantly restricts what types of pods can be deployed to a cluster or project. This policy:
- Prevents pods from running as a privileged user and prevents escalation of privileges.
- Validates that server-required security mechanisms are in place (such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added).
- `unrestricted`
This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.
## Creating Pod Security Policies
1. From the **Global** view, select **Security** > **Pod Security Policies** from the main menu. Then click **Add Policy**.
**Step Result:** The **Add Policy** form opens.
2. Name the policy.
3. Complete each section of the form. Refer to the Kubernetes documentation linked below for more information on what each policy does.
- Basic Policies:
- [Privilege Escalation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation)
- [Host Namespaces][2]
- [Read Only Root Filesystems][1]
- [Capability Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#capabilities)
- [Volume Policy][1]
- [Allowed Host Paths Policy][1]
- [FS Group Policy][1]
- [Host Ports Policy][2]
- [Run As User Policy][3]
- [SELinux Policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#selinux)
- [Supplemental Groups Policy][3]
### What's Next?
You can add a Pod Security Policy (PSPs hereafter) in the following contexts:
- [When creating a cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/)
- [When editing an existing cluster]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/editing-clusters/)
- [When creating a project]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#creating-a-project/)
- [When editing an existing project]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/)
> **Note:** We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.
<!-- links -->
[1]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
[2]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces
[3]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#users-and-groups
content/rancher/v2.5/en/applications/ecm/projects-and-namespaces/_index.md
+198
View File
@@ -0,0 +1,198 @@
---
title: Projects and Kubernetes Namespaces with Rancher
description: Rancher Projects ease the administrative burden of your cluster and support multi-tenancy. Learn to create projects and divide projects into Kubernetes namespaces
weight: 2
---
A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas.
A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.
This section describes how projects and namespaces work with Rancher. It covers the following topics:
- [About namespaces](#about-namespaces)
- [About projects](#about-projects)
- [The cluster's default project](#the-cluster-s-default-project)
- [The system project](#the-system-project)
- [Project authorization](#project-authorization)
- [Pod security policies](#pod-security-policies)
- [Creating projects](#creating-projects)
- [Switching between clusters and projects](#switching-between-clusters-and-projects)
# About Namespaces
A namespace is a concept introduced by Kubernetes. According to the [official Kubernetes documentation on namespaces,](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
> Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all.
Namespaces provide the following functionality:
- **Providing a scope for names:** Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace.
- **Resource quotas:** Namespaces provide a way to divide cluster resources between multiple users.
You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace.
You can assign the following resources directly to namespaces:
- [Workloads]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/workloads/)
- [Load Balancers/Ingress]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/)
- [Service Discovery Records]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/service-discovery/)
- [Persistent Volume Claims]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/)
- [Certificates]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/certificates/)
- [ConfigMaps]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/configmaps/)
- [Registries]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/registries/)
- [Secrets]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/secrets/)
To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.
For more information on creating and moving namespaces, see [Namespaces]({{<baseurl>}}/rancher/v2.x/en/project-admin/namespaces/).
### Role-based access control issues with namespaces and kubectl
Because projects are a concept introduced by Rancher, kubectl does not have the capability to restrict the creation of namespaces to a project the creator has access to.
This means that when standard users with project-scoped permissions create a namespaces with `kubectl`, it may be unusable because `kubectl` doesn't require the new namespace to be scoped within a certain project.
If your permissions are restricted to the project level, it is better to [create a namespace through Rancher]({{<baseurl>}}/rancher/v2.x/en/project-admin/namespaces/#creating-namespaces) to ensure that you will have permission to access the namespace.
If a standard user is a project owner, the user will be able to create namespaces within that project. The Rancher UI will prevent that user from creating namespaces outside the scope of the projects they have access to.
# About Projects
In terms of hierarchy:
- Clusters contain projects
- Projects contain namespaces
You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.
In the base version of Kubernetes, features like role-based access rights or cluster resources are assigned to individual namespaces. A project allows you to save time by giving an individual or a team access to multiple namespaces simultaneously.
You can use projects to perform actions such as:
- Assign users to a group of namespaces (i.e., [project membership]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members)).
- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
- Assign resources to the project.
- Assign Pod Security Policies.
When you create a cluster, two projects are automatically created within it:
- [Default Project](#the-cluster-s-default-project)
- [System Project](#the-system-project)
### The Cluster's Default Project
When you provision a cluster with Rancher, it automatically creates a `default` project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.
If you don't have a need for more than the default namespace, you also do not need more than the **Default** project in Rancher.
If you require another level of organization beyond the **Default** project, you can create more projects in Rancher to isolate namespaces, applications and resources.
### The System Project
_Available as of v2.0.7_
When troubleshooting, you can view the `system` project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers.
To open it, open the **Global** menu, and then select the `system` project for your cluster.
The `system` project:
- Is automatically created when you provision a cluster.
- Lists all namespaces that exist in `v3/settings/system-namespaces`, if they exist.
- Allows you to add more namespaces or move its namespaces to other projects.
- Cannot be deleted because it's required for cluster operations.
>**Note:** In clusters where both:
>
> - The [Canal network plug-in]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#canal) is in use.
> - The Project Network Isolation option is enabled.
>
>The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health.
# Project Authorization
Standard users are only authorized for project access in two situations:
- An administrator, cluster owner or cluster member explicitly adds the standard user to the project's **Members** tab.
- Standard users can access projects that they create themselves.
# Pod Security Policies
Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) at the [project level]({{<baseurl>}}/rancher/v2.x/en/project-admin/pod-security-policies) in addition to the [cluster level.](../pod-security-policy) However, as a best practice, we recommend applying Pod Security Policies at the cluster level.
# Creating Projects
This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.
1. [Name a new project.](#1-name-a-new-project)
2. [Optional: Select a pod security policy.](#2-optional-select-a-pod-security-policy)
3. [Recommended: Add project members.](#3-recommended-add-project-members)
4. [Optional: Add resource quotas.](#4-optional-add-resource-quotas)
### 1. Name a New Project
1. From the **Global** view, choose **Clusters** from the main menu. From the **Clusters** page, open the cluster from which you want to create a project.
1. From the main menu, choose **Projects/Namespaces**. Then click **Add Project**.
1. Enter a **Project Name**.
### 2. Optional: Select a Pod Security Policy
This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
Assigning a PSP to a project will:
- Override the cluster's default PSP.
- Apply the PSP to the project.
- Apply the PSP to any namespaces you add to the project later.
### 3. Recommended: Add Project Members
Use the **Members** section to provide other users with project access and roles.
By default, your user is added as the project `Owner`.
>**Notes on Permissions:**
>
>- Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned.
>- Choose `Custom` to create a custom role on the fly: [Custom Project Roles]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles).
To add members:
1. Click **Add Member**.
1. From the **Name** combo box, search for a user or group that you want to assign project access. Note: You can only search for groups if external authentication is enabled.
1. From the **Role** drop-down, choose a role. For more information, refer to the [documentation on project roles.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/)
### 4. Optional: Add Resource Quotas
_Available as of v2.1.0_
Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas).
To add a resource quota,
1. Click **Add Quota**.
1. Select a [Resource Type]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#resource-quota-types).
1. Enter values for the **Project Limit** and the **Namespace Default Limit**.
1. **Optional:** Specify **Container Default Resource Limit**, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see [Container Default Resource Limit]({{<baseurl>}}/rancher/v2.x/en/project-admin/resource-quotas/#setting-container-default-resource-limit) Note: This option is available as of v2.2.0.
1. Click **Create**.
**Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view.
| Field | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| Project Limit | The overall resource limit for the project. |
| Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit. |
# Switching between Clusters and Projects
To switch between clusters and projects, use the **Global** drop-down available in the main menu.
![Global Menu]({{<baseurl>}}/img/rancher/global-menu.png)
Alternatively, you can switch between projects and clusters using the main menu.
- To switch between clusters, open the **Global** view and select **Clusters** from the main menu. Then open a cluster.
- To switch between projects, open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open.
content/rancher/v2.5/en/applications/ecm/requirements/_index.md
+314
View File
@@ -0,0 +1,314 @@
---
title: Installation Requirements
description: Learn the node requirements for each node running Rancher server when you’re configuring Rancher to run either in a Docker or Kubernetes setup
weight: 1
---
> This section is under construction.
This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.
> It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/) which will run your apps and services.
Make sure the node(s) for the Rancher server fulfill the following requirements:
- [Operating Systems and Docker Requirements](#operating-systems-and-docker-requirements)
- [Hardware Requirements](#hardware-requirements)
- [CPU and Memory](#cpu-and-memory)
- [CPU and Memory for Rancher prior to v2.4.0](#cpu-and-memory-for-rancher-prior-to-v2-4-0)
- [Disks](#disks)
- [Networking Requirements](#networking-requirements)
- [Node IP Addresses](#node-ip-addresses)
- [Port Requirements](#port-requirements)
For a list of best practices that we recommend for running the Rancher server in production, refer to the [best practices section.]({{<baseurl>}}/rancher/v2.x/en/best-practices/deployment-types/)
The Rancher UI works best in Firefox or Chrome.
# Operating Systems and Container Runtime Requirements
Rancher should work with any modern Linux distribution.
For the container runtime, RKE should work with any modern Docker version, while K3s should work with any modern version of Docker or containerd.
Rancher and RKE have been tested and are supported on Ubuntu, CentOS, Oracle Linux, RancherOS, and RedHat Enterprise Linux.
K3s should run on just about any flavor of Linux. However, K3s is tested on the following operating systems and their subsequent non-major releases:
- Ubuntu 16.04 (amd64)
- Ubuntu 18.04 (amd64)
- Raspbian Buster (armhf)
If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow [these steps]({{<baseurl>}}/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables.
If you are installing Rancher on a K3s cluster with Alpine Linux, follow [these steps]({{<baseurl>}}/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup.
For details on which OS and Docker versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)
All supported operating systems are 64-bit x86.
The `ntp` (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.
Some distributions of Linux may have default firewall rules that block communication with Helm. This [how-to guide]({{<baseurl>}}/rancher/v2.x/en/installation/options/firewall) shows how to check the default firewall rules for Oracle Linux and how to open the ports with `firewalld` if necessary.
If you plan to run Rancher on ARM64, see [Running on ARM64 (Experimental).]({{<baseurl>}}/rancher/v2.x/en/installation/options/arm64-platform/)
### Installing Docker
Docker can be installed by following the steps in the official [Docker documentation.](https://docs.docker.com/) Rancher also provides [scripts]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/installing-docker) to install Docker with one command.
# Hardware Requirements
This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.
### CPU and Memory
Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.
{{% tabs %}}
{{% tab "RKE Install Requirements" %}}
These requirements apply to each host in an [RKE Kubernetes cluster where the Rancher server is installed.]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/)
Performance increased in Rancher v2.4.0. For the requirements of Rancher prior to v2.4.0, refer to [this section.](#cpu-and-memory-for-rancher-prior-to-v2-4-0)
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
| --------------- | ---------- | ------------ | -------| ------- |
| Small | Up to 150 | Up to 1500 | 2 | 8 GB |
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB |
| Large | Up to 500 | Up to 5000 | 8 | 32 GB |
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB |
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB |
[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes.
{{% /tab %}}
{{% tab "K3s Install Requirements" %}}
These requirements apply to each host in a [K3s Kubernetes cluster where the Rancher server is installed.]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/)
| Deployment Size | Clusters | Nodes | vCPUs | RAM | Database Size |
| --------------- | ---------- | ------------ | -------| ---------| ------------------------- |
| Small | Up to 150 | Up to 1500 | 2 | 8 GB | 2 cores, 4 GB + 1000 IOPS |
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB | 2 cores, 4 GB + 1000 IOPS |
| Large | Up to 500 | Up to 5000 | 8 | 32 GB | 2 cores, 4 GB + 1000 IOPS |
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS |
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS |
[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes.
{{% /tab %}}
{{% tab "Docker Install Requirements" %}}
These requirements apply to a host with a [single-node]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker) installation of Rancher.
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
| --------------- | -------- | --------- | ----- | ---- |
| Small | Up to 5 | Up to 50 | 1 | 4 GB |
| Medium | Up to 15 | Up to 200 | 2 | 8 GB |
{{% /tab %}}
{{% /tabs %}}
### CPU and Memory for Rancher prior to v2.4.0
{{% accordion label="Click to expand" %}}
These requirements apply to installing Rancher on an RKE Kubernetes cluster prior to Rancher v2.4.0:
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
| --------------- | --------- | ---------- | ----------------------------------------------- | ----------------------------------------------- |
| Small | Up to 5 | Up to 50 | 2 | 8 GB |
| Medium | Up to 15 | Up to 200 | 4 | 16 GB |
| Large | Up to 50 | Up to 500 | 8 | 32 GB |
| X-Large | Up to 100 | Up to 1000 | 32 | 128 GB |
| XX-Large | 100+ | 1000+ | [Contact Rancher](https://rancher.com/contact/) | [Contact Rancher](https://rancher.com/contact/) |
{{% /accordion %}}
### Disks
Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.
# Networking Requirements
This section describes the networking requirements for the node(s) where the Rancher server is installed.
### Node IP Addresses
Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
### Port Requirements
This section describes the port requirements for nodes running the `rancher/rancher` container.
The port requirements are different depending on whether you are installing Rancher on a K3s cluster, on an RKE cluster, or in a single Docker container.
{{% tabs %}}
{{% tab "K3s" %}}
### Ports for Communication with Downstream Clusters
To communicate with downstream clusters, Rancher requires different ports to be open depending on the infrastructure you are using.
For example, if you are deploying Rancher on nodes hosted by an infrastructure provider, port `22` must be open for SSH.
The following diagram depicts the ports that are opened for each [cluster type]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning).
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
![Basic Port Requirements]({{<baseurl>}}/img/rancher/port-communications.svg)
The following tables break down the port requirements for inbound and outbound traffic:
<figcaption>Inbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Source | Description |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used |
| TCP | 443 | <ul><li>server nodes</li><li>agent nodes</li><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl |
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Destination | Description |
| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- |
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
| TCP | 443 | `35.160.43.145/32`, `35.167.242.46/32`, `52.33.59.17/32` | git.rancher.io (catalogs) |
| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine |
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
### Additional Port Requirements for Nodes in a K3s Kubernetes Cluster
You will need to open additional ports to launch the Kubernetes cluster that is required for a high-availability installation of Rancher.
The K3s server needs port 6443 to be accessible by the nodes.
The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.
If you wish to utilize the metrics server, you will need to open port 10250 on each node.
> **Important:** The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.
<figcaption>Inbound Rules for Rancher Server Nodes</figcaption>
| Protocol | Port | Source | Description
|-----|-----|----------------|---|
| TCP | 6443 | K3s server nodes | Kubernetes API
| UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN
| TCP | 10250 | K3s server and agent nodes | kubelet
Typically all outbound traffic is allowed.
{{% /tab %}}
{{% tab "RKE" %}}
### Ports for Communication with Downstream Clusters
To communicate with downstream clusters, Rancher requires different ports to be open depending on the infrastructure you are using.
For example, if you are deploying Rancher on nodes hosted by an infrastructure provider, port `22` must be open for SSH.
The following diagram depicts the ports that are opened for each [cluster type]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning).
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
![Basic Port Requirements]({{<baseurl>}}/img/rancher/port-communications.svg)
The following tables break down the port requirements for inbound and outbound traffic:
<figcaption>Inbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Source | Description |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used |
| TCP | 443 | <ul><li>etcd nodes</li><li>controlplane nodes</li><li>worker nodes</li><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl |
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Destination | Description |
| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- |
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
| TCP | 443 | `35.160.43.145/32`, `35.167.242.46/32`, `52.33.59.17/32` | git.rancher.io (catalogs) |
| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine |
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
### Additional Port Requirements for Nodes in an RKE Kubernetes Cluster
You will need to open additional ports to launch the Kubernetes cluster that is required for a high-availability installation of Rancher.
If you follow the Rancher installation documentation for setting up a Kubernetes cluster using RKE, you will set up a cluster in which all three nodes have all three roles: etcd, controlplane, and worker. In that case, you can refer to this list of requirements for each node with all three roles.
If you installed Rancher on a Kubernetes cluster that doesn't have all three roles on each node, refer to the [port requirements for the Rancher Kubernetes Engine (RKE).]({{<baseurl>}}/rke/latest/en/os/#ports) The RKE docs show a breakdown of the port requirements for each role.
<figcaption>Inbound Rules for Nodes with All Three Roles: etcd, Controlplane, and Worker</figcaption>
Protocol | Port | Source | Description
-----------|------|----------|--------------
TCP | 22 | Linux worker nodes only, and any network that you want to be able to remotely access this node from. | Remote access over SSH
TCP | 80 | Any source that consumes Ingress services | Ingress controller (HTTP)
TCP | 443 | Any source that consumes Ingress services | Ingress controller (HTTPS)
TCP | 2376 | Rancher nodes | Docker daemon TLS port used by Docker Machine (only needed when using Node Driver/Templates)
TCP | 2379 | etcd nodes and controlplane nodes | etcd client requests
TCP | 2380 | etcd nodes and controlplane nodes | etcd peer communication
TCP | 3389 | Windows worker nodes only, and any network that you want to be able to remotely access this node from. | Remote access over RDP
TCP | 6443 | etcd nodes, controlplane nodes, and worker nodes | Kubernetes apiserver
UDP | 8472 | etcd nodes, controlplane nodes, and worker nodes | Canal/Flannel VXLAN overlay networking
TCP | 9099 | the node itself (local traffic, not across nodes) | Canal/Flannel livenessProbe/readinessProbe
TCP | 10250 | controlplane nodes | kubelet
TCP | 10254 | the node itself (local traffic, not across nodes) | Ingress controller livenessProbe/readinessProbe
TCP/UDP | 30000-32767 | Any source that consumes NodePort services | NodePort port range
<figcaption>Outbound Rules for Nodes with All Three Roles: etcd, Controlplane, and Worker</figcaption>
Protocol | Port | Source | Destination | Description
-----------|------|----------|---------------|--------------
TCP | 22 | RKE node | Any node configured in Cluster Configuration File | SSH provisioning of node by RKE
TCP | 443 | Rancher nodes | Rancher agent |
TCP | 2379 | etcd nodes | etcd client requests |
TCP | 2380 | etcd nodes | etcd peer communication |
TCP | 6443 | RKE node | controlplane nodes | Kubernetes API server
TCP | 6443 | controlplane nodes | Kubernetes API server |
UDP | 8472 | etcd nodes, controlplane nodes, and worker nodes | Canal/Flannel VXLAN overlay networking |
TCP | 9099 | the node itself (local traffic, not across nodes) | Canal/Flannel livenessProbe/readinessProbe |
TCP | 10250 | etcd nodes, controlplane nodes, and worker nodes | kubelet |
TCP | 10254 | the node itself (local traffic, not across nodes) | Ingress controller livenessProbe/readinessProbe
{{% /tab %}}
{{% tab "Docker" %}}
### Ports for Communication with Downstream Clusters
For a Docker installation, you only need to open the ports required to enable Rancher to communicate with downstream user clusters.
The port requirements depend on the infrastructure you are using. For example, if you are deploying Rancher on nodes hosted by an infrastructure provider, port `22` must be open for SSH.
The following diagram depicts the ports that are opened for each [cluster type]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning).
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
![Basic Port Requirements]({{<baseurl>}}/img/rancher/port-communications.svg)
The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic:
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
<figcaption>Inbound Rules</figcaption>
| Protocol | Port | Source | Description |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used |
| TCP | 443 | <ul><li>etcd nodes</li><li>controlplane nodes</li><li>worker nodes</li><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl |
<figcaption>Outbound Rules</figcaption>
| Protocol | Port | Source | Description |
| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- |
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
| TCP | 443 | `35.160.43.145/32`, `35.167.242.46/32`, `52.33.59.17/32` | git.rancher.io (catalogs) |
| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine |
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.5/en/applications/ecm/requirements/ports/_index.md
+186
View File
@@ -0,0 +1,186 @@
---
title: Port Requirements
description: Read about port requirements needed in order for Rancher to operate properly, both for Rancher nodes and downstream Kubernetes cluster nodes
weight: 300
---
To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.
## Rancher Nodes
The following table lists the ports that need to be open to and from nodes that are running the Rancher server.
The port requirements differ based on whether Rancher is installed in a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.
{{% tabs %}}
{{% tab "K3s" %}}
The K3s server needs port 6443 to be accessible by the nodes.
The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.
If you wish to utilize the metrics server, you will need to open port 10250 on each node.
> **Important:** The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.
<figcaption>Inbound Rules for Rancher Server Nodes</figcaption>
| Protocol | Port | Source | Description
|-----|-----|----------------|---|
| TCP | 6443 | K3s server nodes | Kubernetes API
| UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN.
| TCP | 10250 | K3s server and agent nodes | kubelet
Typically all outbound traffic is allowed.
{{% /tab %}}
{{% tab "RKE" %}}
<figcaption>Inbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Source | Description |
|-----|-----|----------------|---|
| TCP | 80 | Load Balancer/Reverse Proxy | HTTP traffic to Rancher UI/API |
| TCP | 443 | <ul><li>Load Balancer/Reverse Proxy</li><li>IPs of all cluster nodes and other API/UI clients</li></ul> | HTTPS traffic to Rancher UI/API |
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Destination | Description |
|-----|-----|----------------|---|
| TCP | 443 | `35.160.43.145`,`35.167.242.46`,`52.33.59.17` | Rancher catalog (git.rancher.io) |
| TCP | 22 | Any node created using a node driver | SSH provisioning of node by node driver |
| TCP | 2376 | Any node created using a node driver | Docker daemon TLS port used by node driver |
| TCP | Provider dependent | Port of the Kubernetes API endpoint in hosted cluster | Kubernetes API |
{{% /tab %}}
{{% tab "Docker" %}}
<figcaption>Inbound Rules for Rancher Node</figcaption>
| Protocol | Port | Source | Description
|-----|-----|----------------|---|
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used
| TCP | 443 | <ul><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl
<figcaption>Outbound Rules for Rancher Node</figcaption>
| Protocol | Port | Source | Description |
|-----|-----|----------------|---|
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
| TCP | 443 | `35.160.43.145/32`,`35.167.242.46/32`,`52.33.59.17/32` | git.rancher.io (catalogs) |
| TCP | 2376 | Any node IP from a node created using a node driver | Docker daemon TLS port used by Docker Machine |
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
{{% /tab %}}
{{% /tabs %}}
> **Notes:**
>
> - Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example).
> - Kubernetes recommends TCP 30000-32767 for node port services.
> - For firewalls, traffic may need to be enabled within the cluster and pod CIDR.
## Downstream Kubernetes Cluster Nodes
Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.
The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different [cluster types]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-options).
>**Tip:**
>
>If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in [Commonly Used Ports](#commonly-used-ports) as your port reference instead of the comprehensive tables below.
{{% tabs %}}
{{% tab "Node Pools" %}}
The following table depicts the port requirements for [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) with nodes created in an [Infrastructure Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/).
>**Note:**
>The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.
{{< ports-iaas-nodes >}}
{{% /tab %}}
{{% tab "Custom Nodes" %}}
The following table depicts the port requirements for [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) with [Custom Nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/).
{{< ports-custom-nodes >}}
{{% /tab %}}
{{% tab "Hosted Clusters" %}}
The following table depicts the port requirements for [hosted clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters).
{{< ports-imported-hosted >}}
{{% /tab %}}
{{% tab "Imported Clusters" %}}
The following table depicts the port requirements for [imported clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/).
{{< ports-imported-hosted >}}
{{% /tab %}}
{{% /tabs %}}
## Other Port Considerations
### Commonly Used Ports
These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.
| Protocol | Port | Description |
|:--------: |:----------------: |------------------------------------------------- |
| TCP | 22 | Node driver SSH provisioning |
| TCP | 2376 | Node driver Docker daemon TLS port |
| TCP | 2379 | etcd client requests |
| TCP | 2380 | etcd peer communication |
| UDP | 8472 | Canal/Flannel VXLAN overlay networking |
| UDP | 4789 | Flannel VXLAN overlay networking on Windows cluster |
| TCP | 9099 | Canal/Flannel livenessProbe/readinessProbe |
| TCP | 9796 | Default port required by Monitoring to scrape metrics |
| TCP | 6783 | Weave Port |
| UDP | 6783-6784 | Weave UDP Ports |
| TCP | 10250 | kubelet API |
| TCP | 10254 | Ingress controller livenessProbe/readinessProbe |
| TCP/UDP | 30000-</br>32767 | NodePort port range |
----
### Local Node Traffic
Ports marked as `local traffic` (i.e., `9099 TCP`) in the above requirements are used for Kubernetes healthchecks (`livenessProbe` and`readinessProbe`).
These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.
However, this traffic may be blocked when:
- You have applied strict host firewall policies on the node.
- You are using nodes that have multiple interfaces (multihomed).
In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances.
### Rancher AWS EC2 security group
When using the [AWS EC2 node driver]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group.
| Type | Protocol | Port Range | Source/Destination | Rule Type |
|-----------------|:--------:|:-----------:|------------------------|:---------:|
| SSH | TCP | 22 | 0.0.0.0/0 | Inbound |
| HTTP | TCP | 80 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 443 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 2376 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 2379-2380 | sg-xxx (rancher-nodes) | Inbound |
| Custom UDP Rule | UDP | 4789 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 6443 | 0.0.0.0/0 | Inbound |
| Custom UDP Rule | UDP | 8472 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 10250-10252 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 10256 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 30000-32767 | 0.0.0.0/0 | Inbound |
| Custom UDP Rule | UDP | 30000-32767 | 0.0.0.0/0 | Inbound |
| All traffic | All | All | 0.0.0.0/0 | Outbound |
content/rancher/v2.5/en/applications/ecm/restoring-from-backup/_index.md
+111
View File
@@ -0,0 +1,111 @@
---
title: Restoring an RKE Kubernetes Cluster from Backup
weight: 8
---
etcd backup and recovery for [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) can be easily performed. Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.
Rancher recommends enabling the [ability to set up recurring snapshots of etcd]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots), but [one-time snapshots]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#one-time-snapshots) can easily be taken as well. Rancher allows restore from [saved snapshots](#restoring-a-cluster-from-a-snapshot) or if you don't have any snapshots, you can still [restore etcd](#recovering-etcd-without-a-snapshot).
As of Rancher v2.4.0, clusters can also be restored to a prior Kubernetes version and cluster configuration.
This section covers the following topics:
- [Viewing Available Snapshots](#viewing-available-snapshots)
- [Restoring a Cluster from a Snapshot](#restoring-a-cluster-from-a-snapshot)
- [Recovering etcd without a Snapshot](#recovering-etcd-without-a-snapshot)
- [Enabling snapshot features for clusters created before Rancher v2.2.0](#enabling-snapshot-features-for-clusters-created-before-rancher-v2-2-0)
## Viewing Available Snapshots
The list of all available snapshots for the cluster is available.
1. In the **Global** view, navigate to the cluster that you want to view snapshots.
2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
## Restoring a Cluster from a Snapshot
If your Kubernetes cluster is broken, you can restore the cluster from a snapshot.
Restorations changed in Rancher v2.4.0.
{{% tabs %}}
{{% tab "Rancher v2.4.0+" %}}
Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the `cluster.yml.` These components allow you to select from the following options when restoring a cluster from a snapshot:
- **Restore just the etcd contents:** This restoration is similar to restoring to snapshots in Rancher prior to v2.4.0.
- **Restore etcd and Kubernetes version:** This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
- **Restore etcd, Kubernetes versions and cluster configuration:** This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.
When rolling back to a prior Kubernetes version, the [upgrade strategy options]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/upgrading-kubernetes/#configuring-the-upgrade-strategy) are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state.
> **Prerequisite:** To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots)
1. In the **Global** view, navigate to the cluster that you want to restore from a snapshots.
2. Click the **&#8942; > Restore Snapshot**.
3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.
4. In the **Restoration Type** field, choose one of the restoration options described above.
5. Click **Save**.
**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state.
{{% /tab %}}
{{% tab "Rancher prior to v2.4.0" %}}
> **Prerequisites:**
>
> - Make sure your etcd nodes are healthy. If you are restoring a cluster with unavailable etcd nodes, it's recommended that all etcd nodes are removed from Rancher before attempting to restore. For clusters in which Rancher used node pools to provision [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/), new etcd nodes will automatically be created. For [custom clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/), please ensure that you add new etcd nodes to the cluster.
> - To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots)
1. In the **Global** view, navigate to the cluster that you want to restore from a snapshot.
2. Click the **&#8942; > Restore Snapshot**.
3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.
4. Click **Save**.
**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state.
{{% /tab %}}
{{% /tabs %}}
## Recovering etcd without a Snapshot
If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. Please review the best practices for the what the [number of etcd nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production/#count-of-etcd-nodes) should be in a Kubernetes cluster. If you want to recover your set of etcd nodes, follow these instructions:
1. Keep only one etcd node in the cluster by removing all other etcd nodes.
2. On the single remaining etcd node, run the following command:
```
$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd
```
This command outputs the running command for etcd, save this command to use later.
3. Stop the etcd container that you launched in the previous step and rename it to `etcd-old`.
```
$ docker stop etcd
$ docker rename etcd etcd-old
```
4. Take the saved command from Step 2 and revise it:
- If you originally had more than 1 etcd node, then you need to change `--initial-cluster` to only contain the node that remains.
- Add `--force-new-cluster` to the end of the command.
5. Run the revised command.
6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes) and you want to reuse an old node, you are required to [clean up the nodes]({{<baseurl>}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) before attempting to add them back into a cluster.
# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0
If you have any Rancher launched Kubernetes clusters that were created prior to v2.2.0, after upgrading Rancher, you must [edit the cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots prior to v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/).
content/rancher/v2.5/en/applications/ecm/rke-templates/_index.md
+125
View File
@@ -0,0 +1,125 @@
---
title: Managing RKE Cluster Templates
weight: 9
---
RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters.
RKE is the [Rancher Kubernetes Engine,]({{<baseurl>}}/rke/latest/en/) which is the tool that Rancher uses to provision Kubernetes clusters.
With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users.
RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced.
Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users.
If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template.
As of Rancher v2.3.3, you can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters.
The core features of RKE templates allow DevOps and security teams to:
- Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices
- Prevent less technical users from making uninformed choices when provisioning clusters
- Share different templates with different sets of users and groups
- Delegate ownership of templates to users who are trusted to make changes to them
- Control which users can create templates
- Require users to create clusters from a template
# Configurable Settings
RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider:
- Cloud provider options
- Pod security options
- Network providers
- Ingress controllers
- Network security configuration
- Network plugins
- Private registry URL and credentials
- Add-ons
- Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services
The [add-on section](#add-ons) of an RKE template is especially powerful because it allows a wide range of customization options.
# Scope of RKE Templates
RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider.
RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to [RKE Templates and Hardware]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/rke-templates-and-hardware).
RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.
As of v2.3.3, the settings of an existing cluster can be [saved as an RKE template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the [template is updated]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template), and the cluster is upgraded to [use a newer version of the template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision) The new template can also be used to create new clusters.
# Example Scenarios
When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users.
These [example scenarios]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-scenarios) describe how an organization could use templates to standardize cluster creation.
Some of the example scenarios include the following:
- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-scenarios/#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings.
- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-scenarios/#templates-for-basic-and-advanced-users) so that basic users can have more restricted options and advanced users can use more discretion when creating clusters.
- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-scenarios/#updating-templates-and-clusters-created-with-them) and clusters created from the template can [upgrade to the new version]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision) of the template.
- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to share ownership of the template, this scenario describes how [template ownership can be shared.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-scenarios/#allowing-other-users-to-control-and-share-a-template)
# Template Management
When you create an RKE template, it is available in the Rancher UI from the **Global** view under **Tools > RKE Templates.** When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public.
Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings.
RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision.
In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the **Allow User Override** toggle over each setting in the Rancher UI when the template is created.
For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option.
The documents in this section explain the details of RKE template management:
- [Getting permission to create templates]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creator-permissions/)
- [Creating and revising templates]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/)
- [Enforcing template settings]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/enforcement/#requiring-new-clusters-to-use-a-cluster-template)
- [Overriding template settings]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/overrides/)
- [Sharing templates with cluster creators]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users)
- [Sharing ownership of a template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
An [example YAML configuration file for a template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-yaml) is provided for reference.
# Applying Templates
You can [create a cluster from a template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-a-cluster-template) that you created, or from a template that has been [shared with you.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing)
If the RKE template owner creates a new revision of the template, you can [upgrade your cluster to that revision.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#updating-a-cluster-created-with-an-rke-template)
RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.
As of Rancher v2.3.3, you can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated.
# Standardizing Hardware
RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, you use RKE templates [in conjunction with other tools]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/rke-templates-and-hardware).
# YAML Customization
If you define an RKE template as a YAML file, you can modify this [example RKE template YAML]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/example-yaml). The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the `rancher_kubernetes_engine_config` directive in the YAML.
The RKE documentation also has [annotated]({{<baseurl>}}/rke/latest/en/example-yamls/) `cluster.yml` files that you can use for reference.
For guidance on available options, refer to the RKE documentation on [cluster configuration.]({{<baseurl>}}/rke/latest/en/config-options/)
### Add-ons
The add-on section of the RKE template configuration file works the same way as the [add-on section of a cluster configuration file]({{<baseurl>}}/rke/latest/en/config-options/add-ons/).
The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster.
Some things you could do with add-ons include:
- Install applications on the Kubernetes cluster after it starts
- Install plugins on nodes that are deployed with a Kubernetes daemonset
- Automatically set up namespaces, service accounts, or role binding
The RKE template configuration must be nested within the `rancher_kubernetes_engine_config` directive. To set add-ons, when creating the template, you will click **Edit as YAML.** Then use the `addons` directive to add a manifest, or the `addons_include` directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the [user-defined add-ons documentation.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/)
content/rancher/v2.5/en/applications/ecm/rke-templates/applying-templates/_index.md
+63
View File
@@ -0,0 +1,63 @@
---
title: Applying Templates
weight: 50
---
You can create a cluster from an RKE template that you created, or from a template that has been [shared with you.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing)
RKE templates can be applied to new clusters.
As of Rancher v2.3.3, you can [save the configuration of an existing cluster as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated.
You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
This section covers the following topics:
- [Creating a cluster from an RKE template](#creating-a-cluster-from-an-rke-template)
- [Updating a cluster created with an RKE template](#updating-a-cluster-created-with-an-rke-template)
- [Converting an existing cluster to use an RKE template](#converting-an-existing-cluster-to-use-an-rke-template)
### Creating a Cluster from an RKE Template
To add a cluster [hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters) using an RKE template, use these steps:
1. From the **Global** view, go to the **Clusters** tab.
1. Click **Add Cluster** and choose the infrastructure provider.
1. Provide the cluster name and node template details as usual.
1. To use an RKE template, under the **Cluster Options**, check the box for **Use an existing RKE template and revision.**
1. Choose an existing template and revision from the dropdown menu.
1. Optional: You can edit any settings that the RKE template owner marked as **Allow User Override** when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
1. Click **Save** to launch the cluster.
### Updating a Cluster Created with an RKE Template
When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.
- If the setting allows a user override, you can update these settings in the cluster by [editing the cluster.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/)
- If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.
If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.
As of Rancher v2.3.3, an existing cluster's settings can be [saved as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) In that situation, you can also edit the cluster to update the cluster to a new revision of the template.
> **Note:** You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
### Converting an Existing Cluster to Use an RKE Template
_Available as of v2.3.3_
This section describes how to create an RKE template from an existing cluster.
RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) and the cluster is upgraded to [use a newer version of the template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision)
To convert an existing cluster to use an RKE template,
1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that will be converted to use an RKE template. Click **&#8942;** > **Save as RKE Template.**
1. Enter a name for the template in the form that appears, and click **Create.**
**Results:**
- A new RKE template is created.
- The cluster is converted to use the new template.
- New clusters can be [created from the new template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
content/rancher/v2.5/en/applications/ecm/rke-templates/creating-and-revising/_index.md
+162
View File
@@ -0,0 +1,162 @@
---
title: Creating and Revising Templates
weight: 32
---
This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the **Global** view under **Tools > RKE Templates.**
Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.
Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.
The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.
This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Creating a template](#creating-a-template)
- [Updating a template](#updating-a-template)
- [Deleting a template](#deleting-a-template)
- [Creating a revision based on the default revision](#creating-a-revision-based-on-the-default-revision)
- [Creating a revision based on a cloned revision](#creating-a-revision-based-on-a-cloned-revision)
- [Disabling a template revision](#disabling-a-template-revision)
- [Re-enabling a disabled template revision](#re-enabling-a-disabled-template-revision)
- [Setting a template revision as default](#setting-a-template-revision-as-default)
- [Deleting a template revision](#deleting-a-template-revision)
- [Upgrading a cluster to use a new template revision](#upgrading-a-cluster-to-use-a-new-template-revision)
- [Exporting a running cluster to a new RKE template and revision](#exporting-a-running-cluster-to-a-new-rke-template-and-revision)
### Prerequisites
You can create RKE templates if you have the **Create RKE Templates** permission, which can be [given by an administrator.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creator-permissions)
You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to [the documentation on sharing template ownership.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
### Creating a Template
1. From the **Global** view, click **Tools > RKE Templates.**
1. Click **Add Template.**
1. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
1. Optional: Share the template with other users or groups by [adding them as members.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users) You can also make the template public to share with everyone in the Rancher setup.
1. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.
**Result:** An RKE template with one revision is configured. You can use this RKE template revision later when you [provision a Rancher-launched cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters). After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck **Use an existing RKE Template and Revision** will be unavailable.
### Updating a Template
When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.
You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can [disable it.](#disabling-a-template-revision)
When new template revisions are created, clusters using an older revision of the template are unaffected.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to edit and click the **&#8942; > Edit.**
1. Edit the required information and click **Save.**
1. Optional: You can change the default revision of this template and also change who it is shared with.
**Result:** The template is updated. To apply it to a cluster using an older version of the template, refer to the section on [upgrading a cluster to use a new revision of a template.](#upgrading-a-cluster-to-use-a-new-template-revision)
### Deleting a Template
When you no longer use an RKE template for any of your clusters, you can delete it.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to delete and click the **&#8942; > Delete.**
1. Confirm the deletion when prompted.
**Result:** The template is deleted.
### Creating a Revision Based on the Default Revision
You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to clone and click the **&#8942; > New Revision From Default.**
1. Complete the rest of the form to create a new revision.
**Result:** The RKE template revision is cloned and configured.
### Creating a Revision Based on a Cloned Revision
When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to clone. Then select **&#8942; > Clone Revision.**
1. Complete the rest of the form.
**Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.
### Disabling a Template Revision
When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.
You can disable the revision if it is not being used by any cluster.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to disable. Then select **&#8942; > Disable.**
**Result:** The RKE template revision cannot be used to create a new cluster.
### Re-enabling a Disabled Template Revision
If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to re-enable. Then select **&#8942; > Enable.**
**Result:** The RKE template revision can be used to create a new cluster.
### Setting a Template Revision as Default
When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.
To set an RKE template revision as default,
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template revision that should be default and click the **&#8942; > Set as Default.**
**Result:** The RKE template revision will be used as the default option when clusters are created with the template.
### Deleting a Template Revision
You can delete all revisions of a template except for the default revision.
To permanently delete a revision,
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template revision that should be deleted and click the **&#8942; > Delete.**
**Result:** The RKE template revision is deleted.
### Upgrading a Cluster to Use a New Template Revision
> This section assumes that you already have a cluster that [has an RKE template applied.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates)
> This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available.
To upgrade a cluster to use a new template revision,
1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that you want to upgrade and click **&#8942; > Edit.**
1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision.
1. Click **Save.**
**Result:** The cluster is upgraded to use the settings defined in the new template revision.
### Exporting a Running Cluster to a New RKE Template and Revision
You can save an existing cluster's settings as an RKE template.
This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) and the cluster is upgraded to [use a newer version of the template.]
To convert an existing cluster to use an RKE template,
1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that will be converted to use an RKE template. Click **&#8942;** > **Save as RKE Template.**
1. Enter a name for the template in the form that appears, and click **Create.**
**Results:**
- A new RKE template is created.
- The cluster is converted to use the new template.
- New clusters can be [created from the new template and revision.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
content/rancher/v2.5/en/applications/ecm/rke-templates/creator-permissions/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Template Creator Permissions
weight: 10
---
Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.
For more information on administrator permissions, refer to the [documentation on global permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/).
# Giving Users Permission to Create Templates
Templates can only be created by users who have the global permission **Create RKE Templates.**
Administrators have the global permission to create templates, and only administrators can give that permission to other users.
For information on allowing users to modify existing templates, refer to [Sharing Templates.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing)
Administrators can give users permission to create RKE templates in two ways:
- By editing the permissions of an [individual user](#allowing-a-user-to-create-templates)
- By changing the [default permissions of new users](#allowing-new-users-to-create-templates-by-default)
### Allowing a User to Create Templates
An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps:
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **&#8942; > Edit.**
1. In the **Global Permissions** section, choose **Custom** and select the **Create RKE Templates** role along with any other roles the user should have. Click **Save.**
**Result:** The user has permission to create RKE templates.
### Allowing New Users to Create Templates by Default
Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.
1. From the **Global** view, click **Security > Roles.**
1. Under the **Global** roles tab, go to the role **Create RKE Templates** and click the **&#8942; > Edit**.
1. Select the option **Yes: Default role for new users** and click **Save.**
**Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.
### Revoking Permission to Create Templates
Administrators can remove a user's permission to create templates with the following steps:
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **&#8942; > Edit.**
1. In the **Global Permissions** section, un-check the box for **Create RKE Templates**. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions.
1. Click **Save.**
**Result:** The user cannot create RKE templates.
content/rancher/v2.5/en/applications/ecm/rke-templates/enforcement/_index.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Template Enforcement
weight: 32
---
This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.
By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,
- Only an administrator has the ability to create clusters without a template.
- All standard users must use an RKE template to create a new cluster.
- Standard users cannot create a cluster without using a template.
Users can only create new templates if the administrator [gives them permission.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creator-permissions/#allowing-a-user-to-create-templates)
After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to [upgrade the cluster to a new revision]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/#updating-a-cluster-created-with-an-rke-template) of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the [documentation on revising templates.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template)
# Requiring New Clusters to Use an RKE Template
You might want to require new clusters to use a template to ensure that any cluster launched by a [standard user]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) will use the Kubernetes and/or Rancher settings that are vetted by administrators.
To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:
1. From the **Global** view, click the **Settings** tab.
1. Go to the `cluster-template-enforcement` setting. Click the vertical **&#8942;** and click **Edit.**
1. Set the value to **True** and click **Save.**
**Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator.
# Disabling RKE Template Enforcement
To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:
1. From the **Global** view, click the **Settings** tab.
1. Go to the `cluster-template-enforcement` setting. Click the vertical **&#8942;** and click **Edit.**
1. Set the value to **False** and click **Save.**
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
content/rancher/v2.5/en/applications/ecm/rke-templates/example-scenarios/_index.md
+71
View File
@@ -0,0 +1,71 @@
---
title: Example Scenarios
weight: 5
---
These example scenarios describe how an organization could use templates to standardize cluster creation.
- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone](#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings.
- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,](#templates-for-basic-and-advanced-users) so that basic users have more restricted options and advanced users have more discretion when creating clusters.
- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision](#updating-templates-and-clusters-created-with-them) and clusters created from the template can upgrade to the new version of the template.
- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how [template ownership can be shared.](#allowing-other-users-to-control-and-share-a-template)
# Enforcing a Template Setting for Everyone
Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.
1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as **Allow User Override**.
1. The administrator makes the template public.
1. The administrator turns on template enforcement.
**Results:**
- All Rancher users in the organization have access to the template.
- All new clusters created by [standard users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them.
- All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template.
In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else.
# Templates for Basic and Advanced Users
Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want.
1. First, an administrator turns on [RKE template enforcement.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/enforcement/#requiring-new-clusters-to-use-a-cluster-template) This means that every [standard user]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) in Rancher will need to use an RKE template when they create a cluster.
1. The administrator then creates two templates:
- One template for basic users, with almost every option specified except for access keys
- One template for advanced users, which has most or all options has **Allow User Override** turned on
1. The administrator shares the advanced template with only the advanced users.
1. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster.
**Result:** All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters.
# Updating Templates and Clusters Created with Them
Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes.
In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting.
The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters:
- **Specify Kubernetes v1.15 on the template:** The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster.
- **Allow any Kubernetes version on the template:** When creating a template revision, the template owner can also mark the the Kubernetes version as **Allow User Override** using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes.
- **Allow the latest minor Kubernetes version on the template:** The template owner can also create a template revision in which the Kubernetes version is defined as **Latest v1.14 (Allows patch version upgrades).** This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed.
# Allowing Other Users to Control and Share a Template
Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster.
Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template.
To share ownership of the template with Bob, Alice [adds Bob as an owner of her template.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following:
- [Revise the template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) when the best practices change
- [Disable outdated revisions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#disabling-a-template-revision) of the template so that no new clusters can be created with it
- [Delete the whole template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#deleting-a-template) if the organization wants to go in a different direction
- [Set a certain revision as default]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/#setting-a-template-revision-as-default) when users create a cluster with it. End users of the template will still be able to choose which revision they want to create the cluster with.
- [Share the template]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing) with specific users, make the template available to all Rancher users, or share ownership of the template with another user.
content/rancher/v2.5/en/applications/ecm/rke-templates/example-yaml/_index.md
+112
View File
@@ -0,0 +1,112 @@
---
title: Example YAML
weight: 60
---
Below is an example RKE template configuration file for reference.
The YAML in the RKE template uses the same customization that is used when you create an RKE cluster. However, since the YAML is within the context of a Rancher provisioned RKE cluster, the customization from the RKE docs needs to be nested under the `rancher_kubernetes_engine` directive.
```yaml
#
# Cluster Config
#
docker_root_dir: /var/lib/docker
enable_cluster_alerting: false
# This setting is not enforced. Clusters
# created with this sample template
# would have alerting turned off by default,
# but end users could still turn alerting
# on or off.
enable_cluster_monitoring: true
# This setting is not enforced. Clusters
# created with this sample template
# would have monitoring turned on
# by default, but end users could still
# turn monitoring on or off.
enable_network_policy: false
local_cluster_auth_endpoint:
enabled: true
#
# Rancher Config
#
rancher_kubernetes_engine_config: # Your RKE template config goes here.
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
windows_prefered_cluster: false
```
content/rancher/v2.5/en/applications/ecm/rke-templates/overrides/_index.md
+15
View File
@@ -0,0 +1,15 @@
---
title: Overriding Template Settings
weight: 33
---
When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as **Allow User Override.**
After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as **Allow User Override.** However, if the template is [updated to a new revision]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising) that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster.
When any parameter is set as **Allow User Override** on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time.
The **Allow User Override** model of the RKE template is useful for situations such as:
- Administrators know that some settings will need the flexibility to be frequently updated over time
- End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots
content/rancher/v2.5/en/applications/ecm/rke-templates/rke-templates-and-hardware/_index.md
+70
View File
@@ -0,0 +1,70 @@
---
title: RKE Templates and Infrastructure
weight: 90
---
In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.
Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.
If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.
### Node Templates
[Node templates]({{<baseurl>}}/rancher/v2.x/en/user-settings/node-templates) are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.
### Terraform
Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.
This section focuses on how to use Terraform with the [Rancher 2 Terraform provider](https://www.terraform.io/docs/providers/rancher2/), which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.
Terraform allows you to:
- Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
- Leverage catalog apps and multi-cluster apps
- Codify infrastructure across many platforms, including Rancher and major cloud providers
- Commit infrastructure-as-code to version control
- Easily repeat configuration and setup of infrastructure
- Incorporate infrastructure changes into standard development practices
- Prevent configuration drift, in which some servers become configured differently than others
# How Does Terraform Work?
Terraform is written in files with the extension `.tf`. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.
To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with.
Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.
When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run `terraform apply`, the changes would be deployed.
# Tips for Working with Terraform
- There are examples of how to provide most aspects of a cluster in the [documentation for the Rancher 2 provider.](https://www.terraform.io/docs/providers/rancher2/)
- In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver.
- You can also modify auth in the Terraform provider.
- You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure.
- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware.
# Tip for Creating CIS Benchmark Compliant Clusters
This section describes one way that you can make security and compliance-related config files standard in your clusters.
When you create a [CIS benchmark compliant cluster,]({{<baseurl>}}/rancher/v2.x/en/security/) you have an encryption config file and an audit log config file.
Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the `kube-api-server`.
Then you would make sure that the `kube-api-server` flag in your RKE template uses your CIS-compliant config files.
In this way, you can create flags that comply with the CIS benchmark.
# Resources
- [Terraform documentation](https://www.terraform.io/docs/)
- [Rancher2 Terraform provider documentation](https://www.terraform.io/docs/providers/rancher2/)
- [The RanchCast - Episode 1: Rancher 2 Terraform Provider](https://youtu.be/YNCq-prI8-8): In this demo, Director of Community Jason van Brackel walks through using the Rancher 2 Terraform Provider to provision nodes and create a custom cluster.
content/rancher/v2.5/en/applications/ecm/rke-templates/template-access-and-sharing/_index.md
+61
View File
@@ -0,0 +1,61 @@
---
title: Access and Sharing
weight: 31
---
If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.
Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.
When you share a template, each user can have one of two access levels:
- **Owner:** This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
- **User:** These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as **Make Public (read-only),** all users in your Rancher setup have the User access level for the template.
If you create a template, you automatically become an owner of that template.
If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the [documentation about revising templates.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising)
There are several ways to share templates:
- Add users to a new RKE template during template creation
- Add users to an existing RKE template
- Make the RKE template public, sharing it with all users in the Rancher setup
- Share template ownership with users who are trusted to modify the template
### Sharing Templates with Specific Users or Groups
To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template.
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to share and click the **&#8942; > Edit.**
1. In the **Share Template** section, click on **Add Member**.
1. Search in the **Name** field for the user or group you want to share the template with.
1. Choose the **User** access type.
1. Click **Save.**
**Result:** The user or group can create clusters using the template.
### Sharing Templates with All Users
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to share and click the **&#8942; > Edit.**
1. Under **Share Template,** click **Make Public (read-only).** Then click **Save.**
**Result:** All users in the Rancher setup can create clusters using the template.
### Sharing Ownership of Templates
If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.
In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.
To give Owner access to a user or group,
1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to share and click the **&#8942; > Edit.**
1. Under **Share Template**, click on **Add Member** and search in the **Name** field for the user or group you want to share the template with.
1. In the **Access Type** field, click **Owner.**
1. Click **Save.**
**Result:** The user or group has the Owner access type, and can modify, share, or delete the template.
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/_index.md
+92
View File
@@ -0,0 +1,92 @@
---
title: Setting up Kubernetes Clusters in Rancher
description: Provisioning Kubernetes Clusters
weight: 2
---
Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.
This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts]({{<baseurl>}}/rancher/v2.x/en/overview/concepts) page.
For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/) page.
This section covers the following topics:
<!-- TOC -->
- [Setting up clusters in a hosted Kubernetes provider](#setting-up-clusters-in-a-hosted-kubernetes-cluster)
- [Launching Kubernetes with Rancher](#launching-kubernetes-with-rancher)
- [Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider](#launching-kubernetes-and-provisioning-nodes-in-an-infrastructure-provider)
- [Launching Kubernetes on Existing Custom Nodes](#launching-kubernetes-on-existing-custom-nodes)
- [Importing Existing Clusters](#importing-existing-clusters)
- [Importing and Editing K3s Clusters](#importing-and-editing-k3s-clusters)
<!-- /TOC -->
The following table summarizes the options and settings available for each cluster type:
{{% include file="/rancher/v2.x/en/cluster-provisioning/cluster-capabilities-table" %}}
# Setting up Clusters in a Hosted Kubernetes Provider
In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.
If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.
For more information, refer to the section on [hosted Kubernetes clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters)
# Launching Kubernetes with Rancher
Rancher uses the [Rancher Kubernetes Engine (RKE)]({{<baseurl>}}/rke/latest/en/)as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer.
In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform.
These nodes can be dynamically provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers.
If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it.
For more information, refer to the section on [RKE clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/)
### Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider
Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.
Using Rancher, you can create pools of nodes based on a [node template]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers.
One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration.
The cloud providers available for creating a node template are decided based on the [node drivers]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI.
For more information, refer to the section on [nodes hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/)
### Launching Kubernetes on Existing Custom Nodes
When setting up this type of cluster, Rancher installs Kubernetes on existing [custom nodes,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) which creates a custom cluster.
You can bring any nodes you want to Rancher and use them to create a cluster.
These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines.
# Importing Existing Clusters
In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.
Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. Other Rancher features, including management of cluster, role-based access control, policy, and workloads, are available for imported clusters.
For all imported Kubernetes clusters except for K3s clusters, the configuration of an imported cluster still has to be edited outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters.
In Rancher v2.4, it became possible to import a K3s cluster and upgrade Kubernetes by editing the cluster in the Rancher UI.
For more information, refer to the section on [importing existing clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/)
### Importing and Editing K3s Clusters
_Available as of Rancher v2.4.0_
[K3s]({{<baseurl>}}/k3s/latest/en/) is lightweight, fully compliant Kubernetes distribution. K3s Kubernetes clusters can now be imported into Rancher.
When a K3s cluster is imported, Rancher will recognize it as K3s, and the Rancher UI will expose the following features in addition to the functionality for other imported clusters:
- The ability to upgrade the K3s version
- The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster.
For more information, refer to the section on [imported K3s clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/#additional-features-of-imported-k3s-clusters)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/cluster-capabilities-table/index.md
+22
View File
@@ -0,0 +1,22 @@
---
headless: true
---
| Action | [Rancher launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) | [Hosted Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) | [Imported Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters) |
| --- | --- | ---| ---|
| [Using kubectl and a kubeconfig file to Access a Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/) | ✓ | ✓ | ✓ |
| [Managing Cluster Members]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/cluster-members/) | ✓ | ✓ | ✓ |
| [Editing and Upgrading Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/editing-clusters/) | ✓ | ✓ | * |
| [Managing Nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/nodes) | ✓ | ✓ | ✓ |
| [Managing Persistent Volumes and Storage Classes]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) | ✓ | ✓ | ✓ |
| [Managing Projects, Namespaces and Workloads]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/projects-and-namespaces/) | ✓ | ✓ | ✓ |
| [Using App Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/) | ✓ | ✓ | ✓ |
| [Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/) | ✓ | ✓ | ✓ |
| [Cloning Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cloning-clusters/)| ✓ | ✓ | |
| [Ability to rotate certificates]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/certificate-rotation/) | ✓ | | |
| [Ability to back up your Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/) | ✓ | | |
| [Ability to recover and restore etcd]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/restoring-etcd/) | ✓ | | |
| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/) | ✓ | | |
| [Configuring Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/pod-security-policy/) | ✓ | | |
| [Running Security Scans]({{<baseurl>}}/rancher/v2.x/en/security/security-scan/) | ✓ | | |
/* Cluster configuration options can't be edited for imported clusters, except for [K3s clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/#additional-features-for-imported-k3s-clusters)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/_index.md
+32
View File
@@ -0,0 +1,32 @@
---
title: Setting up Clusters from Hosted Kubernetes Providers
weight: 2
---
In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.
If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.
In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-premise or in an infrastructure provider.
Rancher supports the following Kubernetes providers:
Kubernetes Providers | Available as of |
--- | --- |
[Google GKE (Google Kubernetes Engine)](https://cloud.google.com/kubernetes-engine/) | v2.0.0 |
[Amazon EKS (Amazon Elastic Container Service for Kubernetes)](https://aws.amazon.com/eks/) | v2.0.0 |
[Microsoft AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/services/kubernetes-service/) | v2.0.0 |
[Alibaba ACK (Alibaba Cloud Container Service for Kubernetes)](https://www.alibabacloud.com/product/kubernetes) | v2.2.0 |
[Tencent TKE (Tencent Kubernetes Engine)](https://intl.cloud.tencent.com/product/tke) | v2.2.0 |
[Huawei CCE (Huawei Cloud Container Engine)](https://www.huaweicloud.com/en-us/product/cce.html) | v2.2.0 |
## Hosted Kubernetes Provider Authentication
When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures:
- [Creating a GKE Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke)
- [Creating an EKS Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks)
- [Creating an AKS Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks)
- [Creating an ACK Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack)
- [Creating a TKE Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke)
- [Creating a CCE Cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/ack/_index.md
+48
View File
@@ -0,0 +1,48 @@
---
title: Creating an Aliyun ACK Cluster
shortTitle: Alibaba Cloud Container Service for Kubernetes
weight: 2120
---
_Available as of v2.2.0_
You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the [cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for ACK, but by default, this cluster driver is `inactive`. In order to launch ACK clusters, you will need to [enable the ACK cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning ACK clusters.
## Prerequisites
>**Note**
>Deploying to ACK will incur charges.
1. In Aliyun, activate the following services in their respective consoles.
- [Container Service](https://cs.console.aliyun.com)
- [Resource Orchestration Service](https://ros.console.aliyun.com)
- [RAM](https://ram.console.aliyun.com)
2. Make sure that the account you will be using to create the ACK cluster has the appropriate permissions. Referring to the official Alibaba Cloud documentation about [Role authorization](https://www.alibabacloud.com/help/doc-detail/86483.htm) and [Use the Container Service console as a RAM user](https://www.alibabacloud.com/help/doc-detail/86484.htm) for details.
3. In Alibaba Cloud, create an [access key](https://www.alibabacloud.com/help/doc-detail/53045.html).
4. In Alibaba Cloud, create an [SSH key pair](https://www.alibabacloud.com/help/doc-detail/51793.html). This key is used to access nodes in the Kubernetes cluster.
## Create an ACK Cluster
1. From the **Clusters** page, click **Add Cluster**.
1. Choose **Alibaba ACK**.
1. Enter a **Cluster Name**.
1. {{< step_create-cluster_member-roles >}}
1. Configure **Account Access** for the ACK cluster. Choose the geographical region in which to build your cluster, and input the access key that was created as part of the prerequisite steps.
1. Click **Next: Configure Cluster**, then choose cluster type, the version of Kubernetes and the availability zone.
1. If you choose **Kubernetes** as the cluster type, Click **Next: Configure Master Nodes**, then complete the **Master Nodes** form.
1. Click **Next: Configure Worker Nodes**, then complete the **Worker Nodes** form.
1. Review your options to confirm they're correct. Then click **Create**.
{{< result_create-cluster >}}
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/aks/_index.md
+142
View File
@@ -0,0 +1,142 @@
---
title: Creating an AKS Cluster
shortTitle: Azure Kubernetes Service
weight: 2115
aliases:
- /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service/
---
You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS).
## Prerequisites in Microsoft Azure
>**Note**
>Deploying to AKS will incur charges.
To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the [AKS documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal).
Before creating the service principal, you need to obtain the following information from the [Microsoft Azure Portal](https://portal.azure.com):
- Your subscription ID
- Your tenant ID
- An app ID (also called a client ID)
- Client secret
- A resource group
The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal.
### Setting Up the Service Principal with the Azure Command Line Tool
You can create the service principal by running this command:
```
az ad sp create-for-rbac --skip-assignment
```
The result should show information about the new service principal:
```
{
"appId": "xxxx--xxx",
"displayName": "<SERVICE-PRINCIPAL-NAME>",
"name": "http://<SERVICE-PRINCIPAL-NAME>",
"password": "<SECRET>",
"tenant": "<TENANT NAME>"
}
```
You also need to add roles to the service principal so that it has privileges for communication with the AKS API. It also needs access to create and list virtual networks.
Below is an example command for assigning the Contributor role to a service principal. Contributors can manage anything on AKS but cannot give access to others:
```
az role assignment create \
--assignee $appId \
--scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
--role Contributor
```
You can also create the service principal and give it Contributor privileges by combining the two commands into one. In this command, the scope needs to provide a full path to an Azure resource:
```
az ad sp create-for-rbac \
--scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
--role Contributor
```
### Setting Up the Service Principal from the Azure Portal
You can also follow these instructions to set up a service principal and give it role-based access from the Azure Portal.
1. Go to the Microsoft Azure Portal [home page](https://portal.azure.com).
1. Click **Azure Active Directory.**
1. Click **App registrations.**
1. Click **New registration.**
1. Enter a name. This will be the name of your service principal.
1. Optional: Choose which accounts can use the service principal.
1. Click **Register.**
1. You should now see the name of your service principal under **Azure Active Directory > App registrations.**
1. Click the name of your service principal. Take note of the tenant ID and application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click **Certificates & secrets.**
1. Click **New client secret.**
1. Enter a short description, pick an expiration time, and click **Add.** Take note of the client secret so that you can use it when provisioning the AKS cluster.
**Result:** You have created a service principal and you should be able to see it listed in the **Azure Active Directory** section under **App registrations.** You still need to give the service principal access to AKS.
To give role-based access to your service principal,
1. Click **All Services** in the left navigation bar. Then click **Subscriptions.**
1. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster.
1. Click **Access Control (IAM).**
1. In the **Add role assignment** section, click **Add.**
1. In the **Role** field, select a role that will have access to AKS. For example, you can use the **Contributor** role, which has permission to manage everything except for giving access to other users.
1. In the **Assign access to** field, select **Azure AD user, group, or service principal.**
1. In the **Select** field, select the name of your service principal and click **Save.**
**Result:** Your service principal now has access to AKS.
## Create the AKS Cluster
Use Rancher to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
1. Choose **Azure Kubernetes Service**.
1. Enter a **Cluster Name**.
1. {{< step_create-cluster_member-roles >}}
1. Use your subscription ID, tenant ID, app ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:
- **App ID and tenant ID:** To get the app ID and tenant ID, you can go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal. The app ID and tenant ID are both on the app registration detail page.
- **Client secret:** If you didn't copy the client secret when creating the service principal, you can get a new one if you go to the app registration detail page, then click **Certificates & secrets**, then click **New client secret.**
- **Subscription ID:** You can get the subscription ID is available in the portal from **All services > Subscriptions.**
1. {{< step_create-cluster_cluster-options >}}
1. Complete the **Account Access** form using the output from your Service Principal. This information is used to authenticate with Azure.
1. Use **Nodes** to provision each node in your cluster and choose a geographical region.
[Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys)
<br/>
1. Click **Create**.
<br/>
1. Review your options to confirm they're correct. Then click **Create**.
{{< result_create-cluster >}}
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/cce/_index.md
+82
View File
@@ -0,0 +1,82 @@
---
title: Creating a Huawei CCE Cluster
shortTitle: Huawei Cloud Kubernetes Service
weight: 2130
---
_Available as of v2.2.0_
You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the [cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for CCE, but by default, this cluster driver is `inactive`. In order to launch CCE clusters, you will need to [enable the CCE cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning CCE clusters.
## Prerequisites in Huawei
>**Note**
>Deploying to CCE will incur charges.
1. Find your project ID in Huawei CCE portal. See the CCE documentation on how to [manage your projects](https://support.huaweicloud.com/en-us/usermanual-iam/en-us_topic_0066738518.html).
2. Create an [Access Key ID and Secret Access Key](https://support.huaweicloud.com/en-us/usermanual-iam/en-us_topic_0079477318.html).
## Limitations
Huawei CCE service doesn't support the ability to create clusters with public access through their API. You are required to run Rancher in the same VPC as the CCE clusters that you want to provision.
## Create the CCE Cluster
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Huawei CCE**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. Enter **Project Id**, Access Key ID as **Access Key** and Secret Access Key **Secret Key**. Then Click **Next: Configure cluster**.
6. Fill the following cluster configuration:
|Settings|Description|
|---|---|
| Cluster Type | Which type or node you want to include into the cluster, `VirtualMachine` or `BareMetal`. |
| Description | The description of the cluster. |
| Master Version | The Kubernetes version. |
| Management Scale Count | The max node count of the cluster. The options are 50, 200 and 1000. The larger of the scale count, the more the cost. |
| High Availability | Enable master node high availability. The cluster with high availability enabled will have more cost. |
| Container Network Mode | The network mode used in the cluster. `overlay_l2` and `vpc-router` is supported in `VirtualMachine` type and `underlay_ipvlan` is supported in `BareMetal` type |
| Container Network CIDR | Network CIDR for the cluster. |
| VPC Name | The VPC name which the cluster is going to deploy into. Rancher will create one if it is blank. |
| Subnet Name | The Subnet name which the cluster is going to deploy into. Rancher will create one if it is blank. |
| External Server | This option is reserved for the future we can enable CCE cluster public access via API. For now, it is always disabled. |
| Cluster Label | The labels for the cluster. |
| Highway Subnet | This option is only supported in `BareMetal` type. It requires you to select a VPC with high network speed for the bare metal machines. |
**Note:** If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
7. Fill the following node configuration of the cluster:
|Settings|Description|
|---|---|
| Zone | The available zone at where the node(s) of the cluster is deployed. |
| Billing Mode | The bill mode for the cluster node(s). In `VirtualMachine` type, only `Pay-per-use` is supported. in `BareMetal`, you can choose `Pay-per-use` or `Yearly/Monthly`. |
| Validity Period | This option only shows in `Yearly/Monthly` bill mode. It means how long you want to pay for the cluster node(s). |
| Auto Renew | This option only shows in `Yearly/Monthly` bill mode. It means that the cluster node(s) will renew the `Yearly/Monthly` payment automatically or not. |
| Data Volume Type | Data volume type for the cluster node(s). `SATA`, `SSD` or `SAS` for this option. |
| Data Volume Size | Data volume size for the cluster node(s) |
| Root Volume Type | Root volume type for the cluster node(s). `SATA`, `SSD` or `SAS` for this option. |
| Root Volume Size | Root volume size for the cluster node(s) |
| Node Flavor | The node flavor of the cluster node(s). The flavor list in Rancher UI is fetched from Huawei Cloud. It includes all the supported node flavors. |
| Node Count | The node count of the cluster |
| Node Operating System | The operating system for the cluster node(s). Only `EulerOS 2.2` and `CentOS 7.4` are supported right now. |
| SSH Key Name | The ssh key for the cluster node(s) |
| EIP | The public IP options for the cluster node(s). `Disabled` means that the cluster node(s) are not going to bind a public IP. `Create EIP` means that the cluster node(s) will bind one or many newly created Eips after provisioned and more options will be shown in the UI to set the to-create EIP parameters. And `Select Existed EIP` means that the node(s) will bind to the EIPs you select. |
| EIP Count | This option will only be shown when `Create EIP` is selected. It means how many EIPs you want to create for the node(s). |
| EIP Type | This option will only be shown when `Create EIP` is selected. The options are `5_bgp` and `5_sbgp`. |
| EIP Share Type | This option will only be shown when `Create EIP` is selected. The only option is `PER`. |
| EIP Charge Mode | This option will only be shown when `Create EIP` is selected. The options are pay by `BandWidth` and pay by `Traffic`. |
| EIP Bandwidth Size | This option will only be shown when `Create EIP` is selected. The BandWidth of the EIPs. |
| Authentication Mode | It means enabling `RBAC` or also enabling `Authenticating Proxy`. If you select `Authenticating Proxy`, the certificate which is used for authenticating proxy will be also required. |
| Node Label | The labels for the cluster node(s). |
8. Click **Create** to create the CCE cluster.
{{< result_create-cluster >}}
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/eks/_index.md
+291
View File
@@ -0,0 +1,291 @@
---
title: Creating an EKS Cluster
shortTitle: Amazon EKS
weight: 2110
aliases:
- /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-eks/
---
Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html).
## Prerequisites in Amazon Web Services
>**Note**
>Deploying to Amazon AWS will incur charges. For more information, refer to the [EKS pricing page](https://aws.amazon.com/eks/pricing/).
To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate permissions. For details, refer to the official guide on [Amazon EKS Prerequisites](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#eks-prereqs).
### Amazon VPC
You need to set up an Amazon VPC to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. For more information, refer to the [Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-public-private-vpc.html).
### IAM Policies
Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access.
1. Create a user with programmatic access by following the steps [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
2. Next, create an IAM policy that defines what this user has access to in your AWS account. The required permissions are [here.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/#appendix-minimum-eks-permissions) Follow the steps [here](https://docs.aws.amazon.com/eks/latest/userguide/EKS_IAM_user_policies.html) to create an IAM policy and attach it to your user.
3. Finally, follow the steps [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) to create an access key and secret key for this user.
> **Note:** It's important to regularly rotate your access and secret keys. See this [documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#rotating_access_keys_console) for more information.
For more detailed information on IAM policies for EKS, refer to the official [documentation on Amazon EKS IAM Policies, Roles, and Permissions](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html).
## Architecture
The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS.
![Rancher architecture with EKS hosted cluster]({{<baseurl>}}/img/rancher/rancher-architecture.svg)
## Create the EKS Cluster
Use Rancher to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
1. Choose **Amazon EKS**.
1. Enter a **Cluster Name**.
1. {{< step_create-cluster_member-roles >}}
1. Configure **Account Access** for the EKS cluster. Complete each drop-down and field using the information obtained in [2. Create Access Key and Secret Key](#prerequisites-in-amazon-web-services).
| Setting | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
| Region | From the drop-down choose the geographical region in which to build your cluster. |
| Access Key | Enter the access key that you created in [2. Create Access Key and Secret Key](#2-create-access-key-and-secret-key). |
| Secret Key | Enter the secret key that you created in [2. Create Access Key and Secret Key](#2-create-access-key-and-secret-key). |
1. Click **Next: Select Service Role**. Then choose a [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
Service Role | Description
-------------|---------------------------
Standard: Rancher generated service role | If you choose this role, Rancher automatically adds a service role for use with the cluster.
Custom: Choose from your existing service roles | If you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the [Amazon documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role).
1. Click **Next: Select VPC and Subnet**.
1. Choose an option for **Public IP for Worker Nodes**. Your selection for this option determines what options are available for **VPC & Subnet**.
Option | Description
-------|------------
Yes | When your cluster nodes are provisioned, they're assigned a both a private and public IP address.
No: Private IPs only | When your cluster nodes are provisioned, they're assigned only a private IP address.<br/><br/>If you choose this option, you must also choose a **VPC & Subnet** that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane.
1. Now choose a **VPC & Subnet**. For more information, refer to the AWS documentation for [Cluster VPC Considerations](https://docs.aws.amazon.com/eks/latest/userguide/network_reqs.html). Follow one of the sets of instructions below based on your selection from the previous step.
- [What Is Amazon VPC?](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html)
- [VPCs and Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html)
{{% accordion id="yes" label="Public IP for Worker Nodes—Yes" %}}
If you choose to assign a public IP address to your cluster's worker nodes, you have the option of choosing between a VPC that's automatically generated by Rancher (i.e., **Standard: Rancher generated VPC and Subnet**), or a VPC that you're already created with AWS (i.e., **Custom: Choose from your existing VPC and Subnets**). Choose the option that best fits your use case.
1. Choose a **VPC and Subnet** option.
Option | Description
-------|------------
Standard: Rancher generated VPC and Subnet | While provisioning your cluster, Rancher generates a new VPC and Subnet.
Custom: Choose from your exiting VPC and Subnets | While provisioning your cluster, Rancher configures your nodes to use a VPC and Subnet that you've already [created in AWS](https://docs.aws.amazon.com/vpc/latest/userguide/getting-started-ipv4.html). If you choose this option, complete the remaining steps below.
1. If you're using **Custom: Choose from your existing VPC and Subnets**:
(If you're using **Standard**, skip to [step 11](#select-instance-options))
1. Make sure **Custom: Choose from your existing VPC and Subnets** is selected.
1. From the drop-down that displays, choose a VPC.
1. Click **Next: Select Subnets**. Then choose one of the **Subnets** that displays.
1. Click **Next: Select Security Group**.
{{% /accordion %}}
{{% accordion id="no" label="Public IP for Worker Nodes—No: Private IPs only" %}}
If you chose this option, you must also choose a **VPC & Subnet** that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane. Follow the steps below.
>**Tip:** When using only private IP addresses, you can provide your nodes internet access by creating a VPC constructed with two subnets, a private set and a public set. The private set should have its route tables configured to point toward a NAT in the public set. For more information on routing traffic from private subnets, please see the [official AWS documentation](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html).
1. From the drop-down that displays, choose a VPC.
1. Click **Next: Select Subnets**. Then choose one of the **Subnets** that displays.
1. Click **Next: Select Security Group**.
{{% /accordion %}}
1. <a id="security-group"></a>Choose a **Security Group**. See the documentation below on how to create one.
Amazon Documentation:
- [Cluster Security Group Considerations](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html)
- [Security Groups for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)
- [Create a Security Group](https://docs.aws.amazon.com/vpc/latest/userguide/getting-started-ipv4.html#getting-started-create-security-group)
1. <a id="select-instance-options"></a>Click **Select Instance Options**, and then edit the node options available. Instance type and size of your worker nodes affects how many IP addresses each worker node will have available. See this [documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI) for more information.
Option | Description
-------|------------
Instance Type | Choose the [hardware specs](https://aws.amazon.com/ec2/instance-types/) for the instance you're provisioning.
Custom AMI Override | If you want to use a custom [Amazon Machine Image](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html#creating-an-ami) (AMI), specify it here. By default, Rancher will use the [EKS-optimized AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html) for the EKS version that you chose.
Desired ASG Size | The number of instances that your cluster will provision.
User Data | Custom commands can to be passed to perform automated configuration tasks **WARNING: Modifying this may cause your nodes to be unable to join the cluster.** _Note: Available as of v2.2.0_
1. Click **Create**.
{{< result_create-cluster >}}
## Troubleshooting
For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html).
## AWS Service Events
To find information on any AWS Service events, please see [this page](https://status.aws.amazon.com/).
## Security and Compliance
For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/shared-responsibilty.html).
## Tutorial
This [tutorial](https://aws.amazon.com/blogs/opensource/managing-eks-clusters-rancher/) on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB.
## Appendix - Minimum EKS Permissions
Documented here is a minimum set of permissions necessary to use all functionality of the EKS driver in Rancher.
Resource targeting uses `*` as the ARN of many of the resources created cannot be known prior to creating the EKS cluster in Rancher. Some permissions (for example `ec2:CreateVpc`) are only used in situations where Rancher handles the creation of certain resources.
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EC2Permisssions",
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupIngress",
"ec2:DeleteSubnet",
"ec2:CreateKeyPair",
"ec2:AttachInternetGateway",
"ec2:ReplaceRoute",
"ec2:DeleteRouteTable",
"ec2:AssociateRouteTable",
"ec2:DescribeInternetGateways",
"ec2:CreateRoute",
"ec2:CreateInternetGateway",
"ec2:RevokeSecurityGroupEgress",
"ec2:DescribeAccountAttributes",
"ec2:DeleteInternetGateway",
"ec2:DescribeKeyPairs",
"ec2:CreateTags",
"ec2:CreateRouteTable",
"ec2:DescribeRouteTables",
"ec2:DetachInternetGateway",
"ec2:DisassociateRouteTable",
"ec2:RevokeSecurityGroupIngress",
"ec2:DeleteVpc",
"ec2:CreateSubnet",
"ec2:DescribeSubnets",
"ec2:DeleteKeyPair",
"ec2:DeleteTags",
"ec2:CreateVpc",
"ec2:DescribeAvailabilityZones",
"ec2:CreateSecurityGroup",
"ec2:ModifyVpcAttribute",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:DescribeTags",
"ec2:DeleteRoute",
"ec2:DescribeSecurityGroups",
"ec2:DescribeImages",
"ec2:DescribeVpcs",
"ec2:DeleteSecurityGroup"
],
"Resource": "*"
},
{
"Sid": "EKSPermissions",
"Effect": "Allow",
"Action": [
"eks:DeleteFargateProfile",
"eks:DescribeFargateProfile",
"eks:ListTagsForResource",
"eks:UpdateClusterConfig",
"eks:DescribeNodegroup",
"eks:ListNodegroups",
"eks:DeleteCluster",
"eks:CreateFargateProfile",
"eks:DeleteNodegroup",
"eks:UpdateNodegroupConfig",
"eks:DescribeCluster",
"eks:ListClusters",
"eks:UpdateClusterVersion",
"eks:UpdateNodegroupVersion",
"eks:ListUpdates",
"eks:CreateCluster",
"eks:UntagResource",
"eks:CreateNodegroup",
"eks:ListFargateProfiles",
"eks:DescribeUpdate",
"eks:TagResource"
],
"Resource": "*"
},
{
"Sid": "IAMPermissions",
"Effect": "Allow",
"Action": [
"iam:ListRoleTags",
"iam:RemoveRoleFromInstanceProfile",
"iam:CreateRole",
"iam:AttachRolePolicy",
"iam:AddRoleToInstanceProfile",
"iam:DetachRolePolicy",
"iam:GetRole",
"iam:DeleteRole",
"iam:CreateInstanceProfile",
"iam:ListInstanceProfilesForRole",
"iam:PassRole",
"iam:GetInstanceProfile",
"iam:ListRoles",
"iam:ListInstanceProfiles",
"iam:DeleteInstanceProfile"
],
"Resource": "*"
},
{
"Sid": "CloudFormationPermisssions",
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStackResource",
"cloudformation:ListStackResources",
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStacks",
"cloudformation:ListStacks",
"cloudformation:CreateStack",
"cloudformation:DeleteStack"
],
"Resource": "*"
},
{
"Sid": "AutoScalingPermissions",
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:UpdateAutoScalingGroup",
"autoscaling:TerminateInstanceInAutoScalingGroup",
"autoscaling:CreateOrUpdateTags",
"autoscaling:DeleteAutoScalingGroup",
"autoscaling:CreateAutoScalingGroup",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeLaunchConfigurations",
"autoscaling:DescribeScalingActivities",
"autoscaling:CreateLaunchConfiguration",
"autoscaling:DeleteLaunchConfiguration"
],
"Resource": "*"
}
]
}
```
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/gke/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: Creating a GKE Cluster
shortTitle: Google Kubernetes Engine
weight: 2105
aliases:
- /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-gke/
---
## Prerequisites in Google Kubernetes Engine
>**Note**
>Deploying to GKE will incur charges.
Create a service account using [Google Kubernetes Engine](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts). GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication.
The service account requires the following roles:
- **Compute Viewer:** `roles/compute.viewer`
- **Project Viewer:** `roles/viewer`
- **Kubernetes Engine Admin:** `roles/container.admin`
- **Service Account User:** `roles/iam.serviceAccountUser`
[Google Documentation: Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)
## Create the GKE Cluster
Use {{< product >}} to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Google Kubernetes Engine**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. Either paste your service account private key in the **Service Account** text box or **Read from a file**. Then click **Next: Configure Nodes**.
>**Note:** After submitting your private key, you may have to enable the Google Kubernetes Engine API. If prompted, browse to the URL displayed in the Rancher UI to enable the API.
6. Select your **Cluster Options**, customize your **Nodes** and customize the **Security** for the GKE cluster. Review your options to confirm they're correct. Then click **Create**.
{{< result_create-cluster >}}
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/hosted-kubernetes-clusters/tke/_index.md
+77
View File
@@ -0,0 +1,77 @@
---
title: Creating a Tencent TKE Cluster
shortTitle: Tencent Kubernetes Engine
weight: 2125
---
_Available as of v2.2.0_
You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the [cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for TKE, but by default, this cluster driver is `inactive`. In order to launch TKE clusters, you will need to [enable the TKE cluster driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning TKE clusters.
## Prerequisites in Tencent
>**Note**
>Deploying to TKE will incur charges.
1. Make sure that the account you will be using to create the TKE cluster has the appropriate permissions by referring to the [Cloud Access Management](https://intl.cloud.tencent.com/document/product/598/10600) documentation for details.
2. Create a [Cloud API Secret ID and Secret Key](https://console.cloud.tencent.com/capi).
3. Create a [Private Network and Subnet](https://intl.cloud.tencent.com/document/product/215/4927) in the region that you want to deploy your Kubernetes cluster.
4. Create a [SSH key pair](https://intl.cloud.tencent.com/document/product/213/6092). This key is used to access the nodes in the Kubernetes cluster.
## Create a TKE Cluster
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Tencent TKE**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. Configure **Account Access** for the TKE cluster. Complete each drop-down and field using the information obtained in [Prerequisites](#prerequisites).
| Option | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
| Region | From the drop-down chooses the geographical region in which to build your cluster. |
| Secret ID | Enter the Secret ID that you obtained from the Tencent Cloud Console. |
| Secret Key | Enter the Secret key that you obtained from Tencent Cloud Console. |
6. Click `Next: Configure Cluster` to set your TKE cluster configurations.
| Option | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
| Kubernetes Version | The TKE only supports Kubernetes version 1.10.5 now. |
| Node Count | Enter the amount of worker node you want to purchase for your Kubernetes cluster, up to 100. |
| VPC | Select the VPC name that you have created in the Tencent Cloud Console. |
| Container Network CIDR | Enter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16. |
**Note:** If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
7. Click `Next: Select Instance Type` to choose the instance type that will use for your TKE cluster.
| Option | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
| Availability Zone | Choose the availability zone of the VPC region. |
| Subnet | Select the Subnet that you have created within the VPC, and add a new one if you don't have it in the chosen availability zone. |
| Instance Type | From the drop-down chooses the VM instance type that you want to use for the TKE cluster, default to S2.MEDIUM4 (CPU 2 Memory 4 GiB). |
8. Click `Next: Configure Instance` to configure the VM instance that will use for your TKE cluster.
Option | Description
-------|------------
Operating System | The name of the operating system, currently supports Centos7.2x86_64 or ubuntu16.04.1 LTSx86_64
Security Group | Security group ID, default does not bind any security groups.
Root Disk Type | System disk type. System disk type restrictions are detailed in the [CVM instance configuration](https://cloud.tencent.com/document/product/213/11518).
Root Disk Size | System disk size. Linux system adjustment range is 20 - 50G, step size is 1.
Data Disk Type | Data disk type, default value to the SSD cloud drive
Data Disk Size | Data disk size (GB), the step size is 10
Band Width Type | Type of bandwidth, PayByTraffic or PayByHour
Band Width | Public network bandwidth (Mbps)
Key Pair | Key id, after associating the key can be used to logging to the VM node
9. Click **Create**.
{{< result_create-cluster >}}
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/imported-clusters/_index.md
+179
View File
@@ -0,0 +1,179 @@
---
title: Importing Existing Clusters into Rancher
description: Learn how you can create a cluster in Rancher by importing an existing Kubernetes cluster. Then, you can manage it using Rancher
metaTitle: 'Kubernetes Cluster Management'
metaDescription: 'Learn how you can import an existing Kubernetes cluster and then manage it using Rancher'
weight: 5
---
When managing an imported cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.
Rancher features, including management of cluster, role-based access control, policy, and workloads, are available for imported clusters. Note that Rancher does not automate the provisioning or scaling of imported clusters.
For all imported Kubernetes clusters except for K3s clusters, the configuration of an imported cluster still has to be edited outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters.
Rancher v2.4 added the capability to import a K3s cluster into Rancher, as well as the ability to upgrade Kubernetes by editing the cluster in the Rancher UI.
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Importing a cluster](#importing-a-cluster)
- [Imported K3s clusters](#imported-k3s-clusters)
- [Additional features for imported K3s clusters](#additional-features-for-imported-k3s-clusters)
- [Configuring a K3s Cluster to Enable Importation to Rancher](#configuring-a-k3s-cluster-to-enable-importation-to-rancher)
- [Debug Logging and Troubleshooting for Imported K3s clusters](#debug-logging-and-troubleshooting-for-imported-k3s-clusters)
- [Annotating imported clusters](#annotating-imported-clusters)
# Features
After importing a cluster, the cluster owner can:
- [Manage cluster access]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) through role-based access control
- Enable [monitoring]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) and [logging]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/logging/)
- Enable [Istio]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/)
- Use [pipelines]({{<baseurl>}}/rancher/v2.x/en/project-admin/pipelines/)
- Configure [alerts]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/alerts/) and [notifiers]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/notifiers/)
- Manage [projects]({{<baseurl>}}/rancher/v2.x/en/project-admin/) and [workloads]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/workloads/)
After importing a K3s cluster, the cluster owner can also [upgrade Kubernetes from the Rancher UI.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/upgrading-kubernetes/)
# Prerequisites
If your existing Kubernetes cluster already has a `cluster-admin` role defined, you must have this `cluster-admin` privilege to import the cluster into Rancher.
In order to apply the privilege, you need to run:
```plain
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin \
--user [USER_ACCOUNT]
```
before running the `kubectl` command to import the cluster.
By default, GKE users are not given this privilege, so you will need to run the command before importing GKE clusters. To learn more about role-based access control for GKE, please click [here](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).
> If you are importing a K3s cluster, make sure the `cluster.yml` is readable. It is protected by default. For details, refer to [Configuring a K3s cluster to enable importation to Rancher.](#configuring-a-k3s-cluster-to-enable-importation-to-rancher)
# Importing a Cluster
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Import**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. Click **Create**.
6. The prerequisite for `cluster-admin` privileges is shown (see **Prerequisites** above), including an example command to fulfil the prerequisite.
7. Copy the `kubectl` command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run `kubectl get nodes` to verify before running the command shown in {{< product >}}.
8. If you are using self signed certificates, you will receive the message `certificate signed by unknown authority`. To work around this validation, copy the command starting with `curl` displayed in {{< product >}} to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import.
9. When you finish running the command(s) on your node, click **Done**.
{{< result_import-cluster >}}
> **Note:**
> You can not re-import a cluster that is currently active in a Rancher setup.
# Imported K3s Clusters
You can now import a K3s Kubernetes cluster into Rancher. [K3s]({{<baseurl>}}/k3s/latest/en/) is lightweight, fully compliant Kubernetes distribution. You can also upgrade Kubernetes by editing the K3s cluster in the Rancher UI.
### Additional Features for Imported K3s Clusters
_Available as of v2.4.0_
When a K3s cluster is imported, Rancher will recognize it as K3s, and the Rancher UI will expose the following features in addition to the functionality for other imported clusters:
- The ability to upgrade the K3s version
- The ability to configure the maximum number of nodes that will be upgraded concurrently
- The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster.
### Configuring K3s Cluster Upgrades
> It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider.
The **concurrency** is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the **concurrency,** the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed.
- **Controlplane concurrency:** The maximum number of server nodes to upgrade at a single time; also the maximum unavailable server nodes
- **Worker concurrency:** The maximum number worker nodes to upgrade at the same time; also the maximum unavailable worker nodes
In the K3s documentation, controlplane nodes are called server nodes. These nodes run the Kubernetes master, which maintains the desired state of the cluster. In K3s, these controlplane nodes have the capability to have workloads scheduled to them by default.
Also in the K3s documentation, nodes with the worker role are called agent nodes. Any workloads or pods that are deployed in the cluster can be scheduled to these nodes by default.
### Configuring a K3s Cluster to Enable Importation to Rancher
The K3s server needs to be configured to allow writing to the kubeconfig file.
This can be accomplished by passing `--write-kubeconfig-mode 644` as a flag during installation:
```
$ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644
```
The option can also be specified using the environment variable `K3S_KUBECONFIG_MODE`:
```
$ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -
```
### Debug Logging and Troubleshooting for Imported K3s Clusters
Nodes are upgraded by the system upgrade controller running in the downstream cluster. Based on the cluster configuration, Rancher deploys two [plans](https://github.com/rancher/system-upgrade-controller#example-upgrade-plan) to upgrade K3s nodes: one for controlplane nodes and one for workers. The system upgrade controller follows the plans and upgrades the nodes.
To enable debug logging on the system upgrade controller deployment, edit the [configmap](https://github.com/rancher/system-upgrade-controller/blob/50a4c8975543d75f1d76a8290001d87dc298bdb4/manifests/system-upgrade-controller.yaml#L32) to set the debug environment variable to true. Then restart the `system-upgrade-controller` pod.
Logs created by the `system-upgrade-controller` can be viewed by running this command:
```
kubectl logs -n cattle-system system-upgrade-controller
```
The current status of the plans can be viewed with this command:
```
kubectl get plans -A -o yaml
```
If the cluster becomes stuck in upgrading, restart the `system-upgrade-controller`.
To prevent issues when upgrading, the [Kubernetes upgrade best practices](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) should be followed.
### Annotating Imported Clusters
For all types of imported Kubernetes clusters except for K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured.
Therefore, when Rancher imports a cluster, it assumes that several capabilities are disabled by default. Rancher assumes this in order to avoid exposing UI options to the user even when the capabilities are not enabled in the imported cluster.
However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster.
By annotating an imported cluster, it is possible to indicate to Rancher that a cluster was given a pod security policy, or another capability, outside of Rancher.
This example annotation indicates that a pod security policy is enabled:
```json
"capabilities.cattle.io/pspEnabled": "true"
```
The following annotation indicates Ingress capabilities. Note that that the values of non-primitive objects need to be JSON encoded, with quotations escaped.
```json
"capabilities.cattle.io/ingressCapabilities": "[{"customDefaultBackend":true,"ingressProvider":"asdf"}]"
```
These capabilities can be annotated for the cluster:
- `ingressCapabilities`
- `loadBalancerCapabilities`
- `nodePoolScalingSupported`
- `nodePortRange`
- `pspEnabled`
- `taintSupport`
All the capabilities and their type definitions can be viewed in the Rancher API view, at `[Rancher Server URL]/v3/schemas/capabilities`.
To annotate an imported cluster,
1. Go to the cluster view in Rancher and select **&#8942; > Edit.**
1. Expand the **Labels & Annotations** section.
1. Click **Add Annotation.**
1. Add an annotation to the cluster with the format `capabilities/<capability>: <value>` where `value` is the cluster capability that will be overridden by the annotation. In this scenario, Rancher is not aware of any capabilities of the cluster until you add the annotation.
1. Click **Save.**
**Result:** The annotation does not give the capabilities to the cluster, but it does indicate to Rancher that the cluster has those capabilities.
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/imported-clusters/eks/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: Importing EKS Clusters
weight: 2
---
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/imported-clusters/k3s/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: Importing K3s Kubernetes Clusters
weight: 1
---
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/imported-clusters/rancher-k8s/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: Importing Rancher Kubernetes Clusters
weight: 3
---
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/production-checklist/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Checklist for Production-Ready Clusters
weight: 1
---
In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services.
For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on [node requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements)
This is a shortlist of best practices that we strongly recommend for all production clusters.
For a full list of all the best practices that we recommend, refer to the [best practices section.]({{<baseurl>}}/rancher/v2.x/en/best-practices)
### Node Requirements
* Make sure your nodes fulfill all of the [node requirements,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/) including the port requirements.
### Back up etcd
* Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure [etcd Recurring Snapshots]({{<baseurl>}}/rancher/v2.x/en/backups/backups/ha-backups/#option-a-recurring-snapshots) for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.
### Cluster Architecture
* Nodes should have one of the following role configurations:
* `etcd`
* `controlplane`
* `etcd` and `controlplane`
* `worker` (the `worker` role should not be used or added on nodes with the `etcd` or `controlplane` role)
* Have at least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
* Assign two or more nodes the `controlplane` role for master component high availability.
* Assign two or more nodes the `worker` role for workload rescheduling upon node failure.
For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles)
For more information about the
number of nodes for each Kubernetes role, refer to the section on [recommended architecture.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/)
### Logging and Monitoring
* Configure alerts/notifiers for Kubernetes components (System Service).
* Configure logging for cluster analysis and post-mortems.
### Reliability
* Perform load tests on your cluster to verify that its hardware can support your workloads.
### Networking
* Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for `heartbeat-interval` is `500`, and the default setting for `election-timeout` is `5000`. These [settings for etcd tuning](https://coreos.com/etcd/docs/latest/tuning.html) allow etcd to run in most networks (except really high latency networks).
* Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using [Kubernetes Cloud Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/production-checklist/nodes-and-roles/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: Roles for Nodes in Kubernetes
weight: 1
---
This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster.
This diagram is applicable to Kubernetes clusters [launched with Rancher using RKE.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
![Cluster diagram]({{<baseurl>}}/img/rancher/clusterdiagram.svg)<br/>
<sup>Lines show the traffic flow between components. Colors are used purely for visual aid</sup>
# etcd
Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.
>**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
# controlplane
Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components.
>**Note:** Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
### kube-apiserver
The Kubernetes API server (`kube-apiserver`) scales horizontally. Each node with the role `controlplane` will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.
### kube-controller-manager
The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the `kube-controller-manager` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
### kube-scheduler
The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
# worker
Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components.
# References
* [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/production-checklist/recommended-architecture/_index.md
+74
View File
@@ -0,0 +1,74 @@
---
title: Recommended Cluster Architecture
weight: 1
---
There are three roles that can be assigned to nodes: `etcd`, `controlplane` and `worker`.
# Separating Worker Nodes from Nodes with Other Roles
When designing your cluster(s), you have two options:
* Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the [port requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/).
* Assign the `etcd` and `controlplane` roles to the same nodes. These nodes must meet the hardware requirements for both roles.
In either case, the `worker` role should not be used or added to nodes with the `etcd` or `controlplane` role.
Therefore, each node should have one of the following role configurations:
* `etcd`
* `controlplane`
* Both `etcd` and `controlplane`
* `worker`
# Recommended Number of Nodes with Each Role
The cluster should have:
- At least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
- At least two nodes with the role `controlplane` for master component high availability.
- At least two nodes with the role `worker` for workload rescheduling upon node failure.
For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles)
### Number of Controlplane Nodes
Adding more than one node with the `controlplane` role makes every master component highly available.
### Number of etcd Nodes
The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the `etcd` role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an `etcd` node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.
| Nodes with `etcd` role | Majority | Failure Tolerance |
|--------------|------------|-------------------|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 2 | **1** |
| 4 | 3 | 1 |
| 5 | 3 | **2** |
| 6 | 4 | 2 |
| 7 | 4 | **3** |
| 8 | 5 | 3 |
| 9 | 5 | **4** |
References:
* [Official etcd documentation on optimal etcd cluster size](https://etcd.io/docs/v3.4.0/faq/#what-is-failure-tolerance)
* [Official Kubernetes documentation on operating etcd clusters for Kubernetes](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/)
### Number of Worker Nodes
Adding more than one node with the `worker` role will make sure your workloads can be rescheduled if a node fails.
### Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications
You may have noticed that our [Kubernetes Install]({{<baseurl>}}/rancher/v2.x/en/installation/k8s-install/) instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the `worker` role. However, for your Rancher installation, this three node cluster is valid, because:
* It allows one `etcd` node failure.
* It maintains multiple instances of the master components by having multiple `controlplane` nodes.
* No other workloads than Rancher itself should be created on this cluster.
# References
* [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/_index.md
+34
View File
@@ -0,0 +1,34 @@
---
title: Launching Kubernetes with Rancher
weight: 3
---
You can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses [Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/) (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including:
- Bare-metal servers
- On-premise virtual machines
- Virtual machines hosted by an infrastructure provider
Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them.
RKE clusters include clusters that Rancher launched on Windows nodes or other existing custom nodes, as well as clusters that Rancher launched with new nodes on Azure, Digital Ocean, EC2, or vSphere.
### Requirements
If you use RKE to set up a cluster, your nodes must meet the [requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements) for nodes in downstream user clusters.
### Launching Kubernetes on New Nodes in an Infrastructure Provider
Using Rancher, you can create pools of nodes based on a [node template]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your cloud providers.
One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.
For more information, refer to the section on [launching Kubernetes on new nodes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/)
### Launching Kubernetes on Existing Custom Nodes
In this scenario, you want to install Kubernetes on bare-metal servers, on-premise virtual machines, or virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine.
If you want to reuse a node from a previous custom cluster, [clean the node]({{<baseurl>}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.
For more information, refer to the section on [custom nodes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/cluster-config-reference/_index.md
+394
View File
@@ -0,0 +1,394 @@
---
title: Cluster Configuration Reference
weight: 5
---
As you configure a new cluster that's [provisioned using RKE]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can choose custom Kubernetes options.
You can configure Kubernetes options one of two ways:
- [Rancher UI](#rancher-ui): Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
- [Cluster Config File](#cluster-config-file): Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.
In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. For more information, see the section about the [cluster config file.](#cluster-config-file)
This section is a cluster configuration reference, covering the following topics:
- [Rancher UI Options](#rancher-ui-options)
- [Kubernetes version](#kubernetes-version)
- [Network provider](#network-provider)
- [Kubernetes cloud providers](#kubernetes-cloud-providers)
- [Private registries](#private-registries)
- [Authorized cluster endpoint](#authorized-cluster-endpoint)
- [Advanced Options](#advanced-options)
- [NGINX Ingress](#nginx-ingress)
- [Node port range](#node-port-range)
- [Metrics server monitoring](#metrics-server-monitoring)
- [Pod security policy support](#pod-security-policy-support)
- [Docker version on nodes](#docker-version-on-nodes)
- [Docker root directory](#docker-root-directory)
- [Recurring etcd snapshots](#recurring-etcd-snapshots)
- [Cluster config file](#cluster-config-file)
- [Config file structure in Rancher v2.3.0+](#config-file-structure-in-rancher-v2-3-0+)
- [Config file structure in Rancher v2.0.0-v2.2.x](#config-file-structure-in-rancher-v2-0-0-v2-2-x)
- [Default DNS provider](#default-dns-provider)
- [Rancher specific parameters](#rancher-specific-parameters)
# Rancher UI Options
When creating a cluster using one of the options described in [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), you can configure basic Kubernetes options using the **Cluster Options** section.
### Kubernetes Version
The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on [hyperkube](https://github.com/rancher/hyperkube).
### Network Provider
The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. For more details on the different networking providers, please view our [Networking FAQ]({{<baseurl>}}/rancher/v2.x/en/faq/networking/cni-providers/).
>**Note:** After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications.
Out of the box, Rancher is compatible with the following network providers:
- [Canal](https://github.com/projectcalico/canal)
- [Flannel](https://github.com/coreos/flannel#flannel)
- [Calico](https://docs.projectcalico.org/v3.11/introduction/)
- [Weave](https://github.com/weaveworks/weave) (Available as of v2.2.0)
**Notes on Canal:**
In v2.0.0 - v2.0.4 and v2.0.6, this was the default option for these clusters was Canal with network isolation. With the network isolation automatically enabled, it prevented any pod communication between [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).
As of v2.0.7, if you use Canal, you also have the option of using **Project Network Isolation**, which will enable or disable communication between pods in different [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/).
>**Attention Rancher v2.0.0 - v2.0.6 Users**
>
>- In previous Rancher releases, Canal isolates project network communications with no option to disable it. If you are using any of these Rancher releases, be aware that using Canal prevents all communication between pods in different projects.
>- If you have clusters using Canal and are upgrading to v2.0.7, those clusters enable Project Network Isolation by default. If you want to disable Project Network Isolation, edit the cluster and disable the option.
**Notes on Flannel:**
In v2.0.5, this was the default option, which did not prevent any network isolation between projects.
**Notes on Weave:**
When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a [Config File]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) and the [Weave Network Plug-in Options]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options).
### Kubernetes Cloud Providers
You can configure a [Kubernetes cloud provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider.
>**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider.
If you want to see all the configuration options for a cluster, please click **Show advanced options** on the bottom right. The advanced options are described below:
### Private registries
_Available as of v2.2.0_
The cluster-level private registry configuration is only used for provisioning clusters.
There are two main ways to set up private registries in Rancher: by setting up the [global default registry]({{<baseurl>}}/rancher/v2.x/en/admin-settings/config-private-registry) through the **Settings** tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.
If your private registry requires credentials, you need to pass the credentials to Rancher by editing the cluster options for each cluster that needs to pull images from the registry.
The private registry configuration option tells Rancher where to pull the [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) or [addon images]({{<baseurl>}}/rke/latest/en/config-options/add-ons/) that will be used in your cluster.
- **System images** are components needed to maintain the Kubernetes cluster.
- **Add-ons** are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server.
See the [RKE documentation on private registries]({{<baseurl>}}/rke/latest/en/config-options/private-registries/) for more information on the private registry for components applied during the provisioning of the cluster.
### Authorized Cluster Endpoint
_Available as of v2.2.0_
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.
> The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher [used RKE]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#tools-for-provisioning-kubernetes-clusters) to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS.
This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates.
For more detail on how an authorized cluster endpoint works and why it is used, refer to the [architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#4-authorized-cluster-endpoint)
We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
# Advanced Options
The following options are available when you create clusters in the Rancher UI. They are located under **Advanced Options.**
### NGINX Ingress
Option to enable or disable the [NGINX ingress controller]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/).
### Node Port Range
Option to change the range of ports that can be used for [NodePort services](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport). Default is `30000-32767`.
### Metrics Server Monitoring
Option to enable or disable [Metrics Server]({{<baseurl>}}/rke/latest/en/config-options/add-ons/metrics-server/).
### Pod Security Policy Support
Option to enable and select a default [Pod Security Policy]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies). You must have an existing Pod Security Policy configured before you can use this option.
### Docker Version on Nodes
Option to require [a supported Docker version]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/) installed on the cluster nodes that are added to the cluster, or to allow unsupported Docker versions installed on the cluster nodes.
### Docker Root Directory
If the nodes you are adding to the cluster have Docker configured with a non-default Docker Root Directory (default is `/var/lib/docker`), please specify the correct Docker Root Directory in this option.
### Recurring etcd Snapshots
Option to enable or disable [recurring etcd snapshots]({{<baseurl>}}/rke/latest/en/etcd-snapshots/#etcd-recurring-snapshots).
# Cluster Config File
Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{<baseurl>}}/rke/latest/en/config-options/) in an RKE installation, except for `system_images` configuration. The `system_images` option is not supported when creating a cluster with the Rancher UI or API.
>**Note:** In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: `kube_api` and `kube_controller`.
- To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**.
- To read from an existing RKE file, click **Read from a file**.
![image]({{<baseurl>}}/img/rancher/cluster-options-yaml.png)
The structure of the config file is different depending on your version of Rancher. Below are example config files for Rancher v2.0.0-v2.2.x and for Rancher v2.3.0+.
### Config File Structure in Rancher v2.3.0+
RKE (Rancher Kubernetes Engine) is the tool that Rancher uses to provision Kubernetes clusters. Rancher's cluster config files used to have the same structure as [RKE config files,]({{<baseurl>}}/rke/latest/en/example-yamls/) but the structure changed so that in Rancher, RKE cluster config items are separated from non-RKE config items. Therefore, configuration for your cluster needs to be nested under the `rancher_kubernetes_engine_config` directive in the cluster config file. Cluster config files created with earlier versions of Rancher will need to be updated for this format. An example cluster config file is included below.
{{% accordion id="v2.3.0-cluster-config-file" label="Example Cluster Config File for Rancher v2.3.0+" %}}
```yaml
#
# Cluster Config
#
docker_root_dir: /var/lib/docker
enable_cluster_alerting: false
enable_cluster_monitoring: false
enable_network_policy: false
local_cluster_auth_endpoint:
enabled: true
#
# Rancher Config
#
rancher_kubernetes_engine_config: # Your RKE template config goes here.
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
windows_prefered_cluster: false
```
{{% /accordion %}}
### Config File Structure in Rancher v2.0.0-v2.2.x
An example cluster config file is included below.
{{% accordion id="prior-to-v2.3.0-cluster-config-file" label="Example Cluster Config File for Rancher v2.0.0-v2.2.x" %}}
```yaml
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
```
{{% /accordion %}}
### Default DNS provider
The table below indicates what DNS provider is deployed by default. See [RKE documentation on DNS provider]({{<baseurl>}}/rke/latest/en/config-options/add-ons/dns/) for more information how to configure a different DNS provider. CoreDNS can only be used on Kubernetes v1.12.0 and higher.
| Rancher version | Kubernetes version | Default DNS provider |
|-------------|--------------------|----------------------|
| v2.2.5 and higher | v1.14.0 and higher | CoreDNS |
| v2.2.5 and higher | v1.13.x and lower | kube-dns |
| v2.2.4 and lower | any | kube-dns |
# Rancher specific parameters
_Available as of v2.2.0_
Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML):
### docker_root_dir
See [Docker Root Directory](#docker-root-directory).
### enable_cluster_monitoring
Option to enable or disable [Cluster Monitoring]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/monitoring/).
### enable_network_policy
Option to enable or disable Project Network Isolation.
### local_cluster_auth_endpoint
See [Authorized Cluster Endpoint](#authorized-cluster-endpoint).
Example:
```yaml
local_cluster_auth_endpoint:
enabled: true
fqdn: "FQDN"
ca_certs: "BASE64_CACERT"
```
### Custom Network Plug-in
_Available as of v2.2.4_
You can add a custom network plug-in by using the [user-defined add-on functionality]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) of RKE. You define any add-on that you want deployed after the Kubernetes cluster is deployed.
There are two ways that you can specify an add-on:
- [In-line Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/#in-line-add-ons)
- [Referencing YAML Files for Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/#referencing-yaml-files-for-add-ons)
For an example of how to configure a custom network plug-in by editing the `cluster.yml`, refer to the [RKE documentation.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/custom-network-plugin-example)
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/cluster-config-reference/pod-security-policies/_index.md
+19
View File
@@ -0,0 +1,19 @@
---
title: Assigning Pod Security Policies
weight: 1
---
_Pod Security Policies_ are objects that control security-sensitive aspects of pod specification (like root privileges).
## Adding a Default Pod Security Policy
When you create a new cluster with RKE, you can configure it to apply a PSP immediately. As you create the cluster, use the **Cluster Options** to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster.
>**Prerequisite:**
>Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{<baseurl>}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
>**Note:**
>For security purposes, we recommend assigning a PSP as you create your clusters.
To enable a default Pod Security Policy, set the **Pod Security Policy Support** option to **Enabled**, and then make a selection from the **Default Pod Security Policy** drop-down.
When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster.
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/custom-nodes/_index.md
+113
View File
@@ -0,0 +1,113 @@
---
title: Launching Kubernetes on Existing Custom Nodes
description: To create a cluster with custom nodes, you’ll need to access servers in your cluster and provision them according to Rancher requirements
metaDescription: "To create a cluster with custom nodes, you’ll need to access servers in your cluster and provision them according to Rancher requirements"
weight: 3
---
When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to create a Kubernetes cluster in on-premise bare-metal servers, on-premise virtual machines, or in any node hosted by an infrastructure provider.
To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to the [requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements), which includes some hardware specifications and Docker. After you install Docker on each server, run the command provided in the Rancher UI to turn each server into a Kubernetes node.
This section describes how to set up a custom cluster.
# Creating a Cluster with Custom Nodes
>**Want to use Windows hosts as Kubernetes workers?**
>
>See [Configuring Custom Clusters for Windows]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/) before you start.
<!-- TOC -->
- [1. Provision a Linux Host](#1-provision-a-linux-host)
- [2. Create the Custom Cluster](#2-create-the-custom-cluster)
- [3. Amazon Only: Tag Resources](#3-amazon-only-tag-resources)
<!-- /TOC -->
### 1. Provision a Linux Host
Begin creation of a custom cluster by provisioning a Linux host. Your host can be:
- A cloud-host virtual machine (VM)
- An on-premise VM
- A bare-metal server
If you want to reuse a node from a previous custom cluster, [clean the node]({{<baseurl>}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.
Provision the host according to the [installation requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements) and the [checklist for production-ready clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production)
### 2. Create the Custom Cluster
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Custom**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. {{< step_create-cluster_cluster-options >}}
>**Using Windows nodes as Kubernetes workers?**
>
>- See [Enable the Windows Support Option]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/#enable-the-windows-support-option).
>- The only Network Provider available for clusters with Windows support is Flannel. See [Networking Option]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/#networking-option).
6. <a id="step-6"></a>Click **Next**.
7. From **Node Role**, choose the roles that you want filled by a cluster node.
>**Notes:**
>
>- Using Windows nodes as Kubernetes workers? See [Node Configuration]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/#node-configuration).
>- Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers).
8. <a id="step-8"></a>**Optional**: Click **[Show advanced options]({{<baseurl>}}/rancher/v2.x/en/admin-settings/agent-options/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
9. Copy the command displayed on screen to your clipboard.
10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.
>**Note:** Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed.
11. When you finish running the command(s) on your Linux host(s), click **Done**.
{{< result_create-cluster >}}
### 3. Amazon Only: Tag Resources
If you have configured your cluster to use Amazon as **Cloud Provider**, tag your AWS resources with a cluster ID.
[Amazon Documentation: Tagging Your Amazon EC2 Resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)
>**Note:** You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see [Kubernetes Cloud Providers](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/)
The following resources need to tagged with a `ClusterID`:
- **Nodes**: All hosts added in Rancher.
- **Subnet**: The subnet used for your cluster
- **Security Group**: The security group used for your cluster.
>**Note:** Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer.
The tag that should be used is:
```
Key=kubernetes.io/cluster/<CLUSTERID>, Value=owned
```
`<CLUSTERID>` can be any string you choose. However, the same string must be used on every resource you tag. Setting the tag value to `owned` informs the cluster that all resources tagged with the `<CLUSTERID>` are owned and managed by this cluster.
If you share resources between clusters, you can change the tag to:
```
Key=kubernetes.io/cluster/CLUSTERID, Value=shared
```
# Optional Next Steps
After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:
- **Access your cluster with the kubectl CLI:** Follow [these steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/custom-nodes/agent-options/_index.md
+57
View File
@@ -0,0 +1,57 @@
---
title: Rancher Agent Options
weight: 2500
aliases:
- /rancher/v2.x/en/admin-settings/agent-options/
- /rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options
---
Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to [create a cluster with custom nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes) and add the options to the generated `docker run` command when adding a node.
For an overview of how Rancher communicates with downstream clusters using node agents, refer to the [architecture section.]({{<baseurl>}}/rancher/v2.x/en/overview/architecture/#3-node-agents)
## General options
| Parameter | Environment variable | Description |
| ---------- | -------------------- | ----------- |
| `--server` | `CATTLE_SERVER` | The configured Rancher `server-url` setting which the agent connects to |
| `--token` | `CATTLE_TOKEN` | Token that is needed to register the node in Rancher |
| `--ca-checksum` | `CATTLE_CA_CHECKSUM` | The SHA256 checksum of the configured Rancher `cacerts` setting to validate |
| `--node-name` | `CATTLE_NODE_NAME` | Override the hostname that is used to register the node (defaults to `hostname -s`) |
| `--label` | `CATTLE_NODE_LABEL` | Add node labels to the node. For multiple labels, pass additional `--label` options. (`--label key=value`) |
| `--taints` | `CATTLE_NODE_TAINTS` | Add node taints to the node. For multiple taints, pass additional `--taints` options. (`--taints key=value:effect`) |
## Role options
| Parameter | Environment variable | Description |
| ---------- | -------------------- | ----------- |
| `--all-roles` | `ALL=true` | Apply all roles (`etcd`,`controlplane`,`worker`) to the node |
| `--etcd` | `ETCD=true` | Apply the role `etcd` to the node |
| `--controlplane` | `CONTROL=true` | Apply the role `controlplane` to the node |
| `--worker` | `WORKER=true` | Apply the role `worker` to the node |
## IP address options
| Parameter | Environment variable | Description |
| ---------- | -------------------- | ----------- |
| `--address` | `CATTLE_ADDRESS` | The IP address the node will be registered with (defaults to the IP used to reach `8.8.8.8`) |
| `--internal-address` | `CATTLE_INTERNAL_ADDRESS` | The IP address used for inter-host communication on a private network |
### Dynamic IP address options
For automation purposes, you can't have a specific IP address in a command as it has to be generic to be used for every node. For this, we have dynamic IP address options. They are used as a value to the existing IP address options. This is supported for `--address` and `--internal-address`.
| Value | Example | Description |
| ---------- | -------------------- | ----------- |
| Interface name | `--address eth0` | The first configured IP address will be retrieved from the given interface |
| `ipify` | `--address ipify` | Value retrieved from `https://api.ipify.org` will be used |
| `awslocal` | `--address awslocal` | Value retrieved from `http://169.254.169.254/latest/meta-data/local-ipv4` will be used |
| `awspublic` | `--address awspublic` | Value retrieved from `http://169.254.169.254/latest/meta-data/public-ipv4` will be used |
| `doprivate` | `--address doprivate` | Value retrieved from `http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address` will be used |
| `dopublic` | `--address dopublic` | Value retrieved from `http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address` will be used |
| `azprivate` | `--address azprivate` | Value retrieved from `http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text` will be used |
| `azpublic` | `--address azpublic` | Value retrieved from `http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text` will be used |
| `gceinternal` | `--address gceinternal` | Value retrieved from `http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip` will be used |
| `gceexternal` | `--address gceexternal` | Value retrieved from `http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip` will be used |
| `packetlocal` | `--address packetlocal` | Value retrieved from `https://metadata.packet.net/2009-04-04/meta-data/local-ipv4` will be used |
| `packetpublic` | `--address packetlocal` | Value retrieved from `https://metadata.packet.net/2009-04-04/meta-data/public-ipv4` will be used |
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/infrastructure-provider/_index.md
+133
View File
@@ -0,0 +1,133 @@
---
title: Launching Kubernetes on New Nodes in an Infrastructure Provider
weight: 2
---
Using Rancher, you can create pools of nodes based on a [node template]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers.
One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.
The available cloud providers to create a node template are decided based on active [node drivers]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers).
This section covers the following topics:
- [Node templates](#node-templates)
- [Node labels](#node-labels)
- [Node taints](#node-taints)
- [Administrator control of node templates](#administrator-control-of-node-templates)
- [Node pools](#node-pools)
- [Node pool taints](#node-pool-taints)
- [About node auto-replace](#about-node-auto-replace)
- [Enabling node auto-replace](#enabling-node-auto-replace)
- [Disabling node auto-replace](#disabling-node-auto-replace)
- [Cloud credentials](#cloud-credentials)
- [Node drivers](#node-drivers)
# Node Templates
A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses [Docker Machine](https://docs.docker.com/machine/) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher.
After you create a node template in Rancher, it's saved so that you can use this template again to create node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile.
### Node Labels
You can add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) on each node template, so that any nodes created from the node template will automatically have these labels on them.
### Node Taints
_Available as of Rancher v2.3.0_
You can add [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) on each node template, so that any nodes created from the node template will automatically have these taints on them.
Since taints can be added at a node template and node pool, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.
### Administrator Control of Node Templates
_Available as of v2.3.3_
Administrators can control all node templates. Admins can now maintain all the node templates within Rancher. When a node template owner is no longer using Rancher, the node templates created by them can be managed by administrators so the cluster can continue to be updated and maintained.
To access all node templates, an administrator will need to do the following:
1. In the Rancher UI, click the user profile icon in the upper right corner.
1. Click **Node Templates.**
**Result:** All node templates are listed and grouped by owner. The templates can be edited or cloned by clicking the **&#8942;.**
# Node Pools
Using Rancher, you can create pools of nodes based on a [node template](#node-templates). The benefit of using a node pool is that if a node is destroyed or deleted, you can increase the number of live nodes to compensate for the node that was lost. The node pool helps you ensure that the count of the node pool is as expected.
Each node pool is assigned with a [node component]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#kubernetes-cluster-node-components) to specify how these nodes should be configured for the Kubernetes cluster.
### Node Pool Taints
_Available as of Rancher v2.3.0_
If you haven't defined [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) on your node template, you can add taints for each node pool. The benefit of adding taints at a node pool is beneficial over adding it at a node template is that you can swap out the node templates without worrying if the taint is on the node template.
For each taint, they will automatically be added to any created node in the node pool. Therefore, if you add taints to a node pool that have existing nodes, the taints won't apply to existing nodes in the node pool, but any new node added into the node pool will get the taint.
When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.
### About Node Auto-replace
_Available as of Rancher v2.3.0_
If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes.
> **Important:** Self-healing node pools are designed to help you replace worker nodes for **stateless** applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.
{{% accordion id="how-does-node-auto-replace-work" label="How does Node Auto-replace Work?" %}}
Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the `--node-monitor-period` flag of the `kube-controller`). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool.
{{% /accordion %}}
### Enabling Node Auto-replace
When you create the node pool, you can specify the amount of time in minutes that Rancher will wait to replace an unresponsive node.
1. In the form for creating a cluster, go to the **Node Pools** section.
1. Go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
1. Fill out the rest of the form for creating a cluster.
**Result:** Node auto-replace is enabled for the node pool.
You can also enable node auto-replace after the cluster is created with the following steps:
1. From the Global view, click the Clusters tab.
1. Go to the cluster where you want to enable node auto-replace, click the vertical &#8942; **(…)**, and click **Edit.**
1. In the **Node Pools** section, go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
1. Click **Save.**
**Result:** Node auto-replace is enabled for the node pool.
### Disabling Node Auto-replace
You can disable node auto-replace from the Rancher UI with the following steps:
1. From the Global view, click the Clusters tab.
1. Go to the cluster where you want to enable node auto-replace, click the vertical &#8942; **(…)**, and click **Edit.**
1. In the **Node Pools** section, go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter 0.
1. Click **Save.**
**Result:** Node auto-replace is disabled for the node pool.
# Cloud Credentials
_Available as of v2.2.0_
Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits:
- Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time.
- After the cloud credential is created, it can be re-used to create additional node templates.
- Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once.
> **Note:** As of v2.2.0, the default `active` [node drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/) and any node driver, that has fields marked as `password`, are required to use cloud credentials. If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it.
After cloud credentials are created, the user can start [managing the cloud credentials that they created]({{<baseurl>}}/rancher/v2.x/en/user-settings/cloud-credentials/).
# Node Drivers
If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#activating-deactivating-node-drivers), or you can [add your own custom node driver]({{<baseurl>}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#adding-custom-node-drivers).
content/rancher/v2.5/en/applications/ecm/setting-up-k8s/rke-clusters/infrastructure-provider/azure/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Creating an Azure Cluster
shortTitle: Azure
weight: 2220
aliases:
- /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-azure/
---
Use {{< product >}} to create a Kubernetes cluster in Azure.
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Azure**.
3. Enter a **Cluster Name**.
4. {{< step_create-cluster_member-roles >}}
5. {{< step_create-cluster_cluster-options >}}
6. {{< step_create-cluster_node-pools >}}
1. Click **Add Node Template**.
2. Complete the **Azure Options** form.
- **Account Access** stores your account information for authenticating with Azure. Note: As of v2.2.0, account access information is stored as a cloud credentials. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. To create a new cloud credential, enter **Name** and **Account Access** data, then click **Create.**
- **Placement** sets the geographical region where your cluster is hosted and other location metadata.
- **Network** configures the networking used in your cluster.
- **Instance** customizes your VM configuration.
3. {{< step_rancher-template >}}
4. Click **Create**.
5. **Optional:** Add additional node pools.
<br>
7. Review your options to confirm they're correct. Then click **Create**.
{{< result_create-cluster >}}
# Optional Next Steps
After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:
- **Access your cluster with the kubectl CLI:** Follow [these steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/cluster-access/kubectl/#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

Some files were not shown because too many files have changed in this diff Show More