mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 12:38:05 +00:00
Remove unused version-2.6 files
This commit is contained in:
Billy Tat
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Authentication, Permissions and Global Configuration
|
||||
weight: 6
|
||||
---
|
||||
|
||||
After installation, the [system administrator]({{<baseurl>}}/rancher/v2.6/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.6/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.6/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.6/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.6/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
|
||||
|
||||
For more information, see [Provisioning Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/drivers/).
|
||||
|
||||
## Adding Kubernetes Versions into Rancher
|
||||
|
||||
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.6/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.6/en/admin-settings/k8s-metadata/)
|
||||
|
||||
Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.6/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.6/en/admin-settings/k8s-metadata/).
|
||||
|
||||
## Enabling Experimental Features
|
||||
|
||||
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.6/en/installation/resources/feature-flags/)
|
||||
@@ -1,206 +0,0 @@
|
||||
---
|
||||
title: Configuring Active Directory (AD)
|
||||
weight: 1112
|
||||
---
|
||||
|
||||
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.6/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.6/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 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.
|
||||
>
|
||||
> - Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15.
|
||||
>
|
||||
> - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0".
|
||||
>
|
||||
> - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container.
|
||||
|
||||
## Configuration Steps
|
||||
### Open Active Directory Configuration
|
||||
|
||||
1. Log into the Rancher UI using the initial local `admin` account.
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **ActiveDirectory**. The **Authentication Provider: ActiveDirectory** form will be displayed.
|
||||
1. Fill out the form. For help, refer to the details on configuration options below.
|
||||
1. Click **Enable**.
|
||||
|
||||
### 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>(|(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>(|(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 organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible to avoid potential performance issues when there is a large amount of nested memberships). |
|
||||
|
||||
---
|
||||
|
||||
### 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, i.e., `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 organization 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.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
title: Authentication
|
||||
weight: 10
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
## External vs. Local Authentication
|
||||
|
||||
The Rancher authentication proxy integrates with the following external authentication services.
|
||||
|
||||
| Auth Service |
|
||||
| ------------------------------------------------------------------------------------------------ |
|
||||
| [Microsoft Active Directory]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ad/) |
|
||||
| [GitHub]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/github/) |
|
||||
| [Microsoft Azure AD]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/azure-ad/) |
|
||||
| [FreeIPA]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/freeipa/) |
|
||||
| [OpenLDAP]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/openldap/) |
|
||||
| [Microsoft AD FS]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/) |
|
||||
| [PingIdentity]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ping-federate/) |
|
||||
| [Keycloak (OIDC)]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-oidc/) |
|
||||
| [Keycloak (SAML)]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-saml/) |
|
||||
| [Okta]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/okta/) |
|
||||
| [Google OAuth]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/google/) |
|
||||
| [Shibboleth]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/shibboleth) |
|
||||
|
||||
<br/>
|
||||
However, Rancher also provides [local authentication]({{<baseurl>}}/rancher/v2.6/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.6/en/admin-settings/rbac/).
|
||||
|
||||
> **Note:** Local authentication does not support creating or managing groups.
|
||||
|
||||
For more information, see [Users and Groups]({{<baseurl>}}/rancher/v2.6/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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Auth Provider**.
|
||||
1. After setting up the configuration details for an auth provider, 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.
|
||||
|
||||
|
||||
|
||||
2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.
|
||||
|
||||
|
||||
|
||||
3. After you complete configuration, Rancher automatically signs out the local principal.
|
||||
|
||||
|
||||
|
||||
4. Then, Rancher automatically signs you back in as the external principal.
|
||||
|
||||
|
||||
|
||||
5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.
|
||||
|
||||
|
||||
|
||||
6. The external principal and the local principal share the same access rights.
|
||||
@@ -1,205 +0,0 @@
|
||||
---
|
||||
title: Configuring Azure AD
|
||||
weight: 1115
|
||||
---
|
||||
|
||||
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 a new client secret](#2-create-a-new-client-secret)
|
||||
- [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher)
|
||||
- [4. Add a Reply URL](#4-add-a-reply-url)
|
||||
- [5. Copy Azure Application Data](#5-copy-azure-application-data)
|
||||
- [6. Configure Azure AD in Rancher](#6-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.
|
||||
|
||||
|
||||
|
||||
1. Click **New registrations** and complete the **Create** form.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
1. From the navigation pane on left, click **Certificates and Secrets**.
|
||||
|
||||
1. Click **New client secret**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
1. Click **Add a permission**.
|
||||
|
||||
1. From the **Azure Active Directory Graph**, select the following **Delegated Permissions**:
|
||||
|
||||
|
||||
|
||||
<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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
### 6. 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.
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **AzureAD**.
|
||||
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 **Enable**.
|
||||
|
||||
**Result:** Azure Active Directory authentication is configured.
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: Configuring FreeIPA
|
||||
weight: 1114
|
||||
---
|
||||
|
||||
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.6/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_).
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **FreeIPA**.
|
||||
1. 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.
|
||||
|
||||
1. 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.
|
||||
|
||||
1. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication.
|
||||
1. Click **Enable**.
|
||||
|
||||
**Result:**
|
||||
|
||||
- FreeIPA authentication is configured.
|
||||
- You are signed into Rancher with your FreeIPA account (i.e., the _external principal_).
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Configuring GitHub
|
||||
weight: 1116
|
||||
---
|
||||
|
||||
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.6/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_).
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **GitHub**.
|
||||
1. Follow the directions displayed to set up 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.
|
||||
|
||||
1. 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.
|
||||
|
||||
1. Click **Authenticate with GitHub**.
|
||||
|
||||
1. 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/>
|
||||
1. Click **Enable**.
|
||||
|
||||
**Result:**
|
||||
|
||||
- GitHub authentication is configured.
|
||||
- You are signed into Rancher with your GitHub account (i.e., the _external principal_).
|
||||
@@ -1,112 +0,0 @@
|
||||
---
|
||||
title: Configuring Google OAuth
|
||||
weight: 10
|
||||
---
|
||||
|
||||
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.6/en/admin-settings/rbac/global-permissions/) 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:
|
||||
|
||||
|
||||
# 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**.
|
||||
|
||||
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)
|
||||
|
||||
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**.
|
||||
|
||||
1. Don't provide any roles on the **Service account permissions** page and click **Continue**
|
||||
|
||||
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.
|
||||
|
||||
|
||||
**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**.
|
||||
|
||||
|
||||
1. Go to the [**Domain-wide Delegation** page.](https://admin.google.com/ac/owl/domainwidedelegation)
|
||||
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.6/en/admin-settings/rbac/global-permissions) role. This user is also called the local principal.
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
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 **Enable**.
|
||||
|
||||
**Result:** Google authentication is successfully configured.
|
||||
-137
@@ -1,137 +0,0 @@
|
||||
---
|
||||
title: Configuring Keycloak (OIDC)
|
||||
description: Create a Keycloak OpenID Connect (OIDC) client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins
|
||||
weight: 1200
|
||||
---
|
||||
If your organization uses [Keycloak Identity Provider (IdP)](https://www.keycloak.org) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. Rancher supports integration with Keycloak using the OpenID Connect (OIDC) protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. This page describes the process to configure Rancher to work with Keycloak using the OIDC protocol.
|
||||
|
||||
If you prefer to use Keycloak with the SAML protocol instead, refer to [this page]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-saml/).
|
||||
|
||||
If you have an existing configuration using the SAML protocol and want to switch to the OIDC protocol, refer to [this section](#migrating-from-saml-to-oidc).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- On Rancher, Keycloak (SAML) is disabled.
|
||||
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
|
||||
- In Keycloak, create a [new OIDC client](https://www.keycloak.org/docs/latest/server_admin/#oidc-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#oidc-clients) for help.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Client ID` | <CLIENT_ID> (e.g. `rancher`)
|
||||
`Name` | <CLIENT_NAME> (e.g. `rancher`)
|
||||
`Client Protocol` | `openid-connect`
|
||||
`Access Type` | `confidential`
|
||||
`Valid Redirect URI` | `https://yourRancherHostURL/verify-auth`
|
||||
|
||||
- In the new OIDC client, create [Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers) to expose the users fields.
|
||||
- Create a new "Groups Mapper" with the settings below.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Groups Mapper`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `groups`
|
||||
`Add to ID token` | `OFF`
|
||||
`Add to access token` | `OFF`
|
||||
`Add to user info` | `ON`
|
||||
|
||||
- Create a new "Client Audience" with the settings below.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Client Audience`
|
||||
`Mapper Type` | `Audience`
|
||||
`Included Client Audience` | <CLIENT_NAME>
|
||||
`Add to access token` | `ON`
|
||||
|
||||
- Create a new "Groups Path" with the settings below.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Group Path`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `full_group_path`
|
||||
`Full group path` | `ON`
|
||||
`Add to user info` | `ON`
|
||||
|
||||
## Configuring Keycloak in Rancher
|
||||
|
||||
1. In the Rancher UI, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Auth Provider**.
|
||||
1. Select **Keycloak (OIDC)**.
|
||||
1. Complete the **Configure a Keycloak OIDC account** form. For help with filling the form, see the [configuration reference](#configuration-reference).
|
||||
1. After you complete the **Configure a Keycloak OIDC account** form, click **Enable**.
|
||||
|
||||
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.
|
||||
|
||||
>**Note:** You may need to disable your popup blocker to see the IdP login page.
|
||||
|
||||
**Result:** Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign into Rancher using their Keycloak logins.
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
| Field | Description |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Client ID | The `Client ID` of your Keycloak client. |
|
||||
| Client Secret | The generated `Secret` of your Keycloak client. In the Keycloak console, select **Clients**, select the client you created, select the **Credentials** tab and copy the value of the `Secret` field. |
|
||||
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. Required if HTTPS/SSL is enabled on your Keycloak server. |
|
||||
| Endpoints | Choose whether to use the generated values for the `Rancher URL`, `Issue`, and `Auth Endpoint` fields or to provide manual overrides if incorrect. |
|
||||
| Keycloak URL | The URL for your Keycloak server. |
|
||||
| Keycloak Realm | The name of the realm in which the Keycloak client was created in. |
|
||||
| Rancher URL | The URL for your Rancher Server. |
|
||||
| Issuer | The URL of your IdP. |
|
||||
| Auth Endpoint | The URL where users are redirected to authenticate. |
|
||||
|
||||
## Migrating from SAML to OIDC
|
||||
|
||||
This section describes the process to transition from using Rancher with Keycloak (SAML) to Keycloak (OIDC).
|
||||
|
||||
### Reconfigure Keycloak
|
||||
|
||||
1. Change the existing client to use the OIDC protocol. In the Keycloak console, select **Clients**, select the SAML client to migrate, select the **Settings** tab, change `Client Protocol` from `saml` to `openid-connect`, and click **Save**
|
||||
|
||||
1. Verify the `Valid Redirect URIs` are still valid.
|
||||
|
||||
1. Select the **Mappers** tab and create a new Mapper with the settings below.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Groups Mapper`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `groups`
|
||||
`Add to ID token` | `ON`
|
||||
`Add to access token` | `ON`
|
||||
`Add to user info` | `ON`
|
||||
|
||||
### Reconfigure Rancher
|
||||
|
||||
Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled.
|
||||
|
||||
1. In the Rancher UI, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Auth Provider**.
|
||||
1. Select **Keycloak (SAML)**.
|
||||
1. Click **Disable**.
|
||||
|
||||
Configure Rancher to use Keycloak (OIDC) by following the steps in [this section](#configuring-keycloak-in-rancher).
|
||||
|
||||
> **Note:** After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated.
|
||||
|
||||
## Annex: Troubleshooting
|
||||
|
||||
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration options of your OIDC client. You may also inspect the Rancher logs to help pinpoint what's causing issues. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
|
||||
|
||||
All Keycloak related log entries will be prepended with either `[generic oidc]` or `[keycloak oidc]`.
|
||||
|
||||
### You are not redirected to Keycloak
|
||||
|
||||
When you fill the **Configure a Keycloak OIDC account** form and click on **Enable**, you are not redirected to your IdP.
|
||||
|
||||
* Verify your Keycloak client configuration.
|
||||
|
||||
### The generated `Issuer` and `Auth Endpoint` are incorrect
|
||||
|
||||
* On the **Configure a Keycloak OIDC account** form, change **Endpoints** to `Specify (advanced)` and override the `Issuer` and `Auth Endpoint` values. To find the values, go to the Keycloak console and select **Realm Settings**, select the **General** tab, and click **OpenID Endpoint Configuration**. The JSON output will display values for `issuer` and `authorization_endpoint`.
|
||||
|
||||
### Keycloak Error: "Invalid grant_type"
|
||||
|
||||
* In some cases, this error message may be misleading and is actually caused by setting the `Valid Redirect URI` incorrectly.
|
||||
-179
@@ -1,179 +0,0 @@
|
||||
---
|
||||
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: 1200
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
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` | Either `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` or the value configured in the `Entry ID Field` of the Rancher Keycloak configuration<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.
|
||||
|
||||
{{< img "/img/rancher/keycloak/keycloak-saml-client-configuration.png" "">}}
|
||||
|
||||
- In the new SAML client, create Mappers to expose the users fields
|
||||
- Add all "Builtin Protocol Mappers"
|
||||
{{< img "/img/rancher/keycloak/keycloak-saml-client-builtin-mappers.png" "">}}
|
||||
- Create a new "Group list" mapper to map the member attribute to a user's groups
|
||||
{{< img "/img/rancher/keycloak/keycloak-saml-client-group-mapper.png" "">}}
|
||||
|
||||
## Getting the IDP Metadata
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Keycloak 5 and earlier">
|
||||
|
||||
To get the IDP metadata, export a `metadata.xml` file from your Keycloak client.
|
||||
From the **Installation** tab, choose the **SAML Metadata IDPSSODescriptor** format option and download your file.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Keycloak 6-13">
|
||||
|
||||
1. From the **Configure** section, click the **Realm Settings** tab.
|
||||
1. Click the **General** tab.
|
||||
1. From the **Endpoints** field, click **SAML 2.0 Identity Provider Metadata**.
|
||||
|
||||
Verify the IDP metadata contains the following attributes:
|
||||
|
||||
```
|
||||
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
|
||||
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
|
||||
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
||||
```
|
||||
|
||||
Some browsers, such as Firefox, may render/process the document such that the contents appear to have been modified, and some attributes appear to be missing. In this situation, use the raw response data that can be found using your browser.
|
||||
|
||||
The following is an example process for Firefox, but will vary slightly for other browsers:
|
||||
|
||||
1. Press **F12** to access the developer console.
|
||||
1. Click the **Network** tab.
|
||||
1. From the table, click the row containing `descriptor`.
|
||||
1. From the details pane, click the **Response** tab.
|
||||
1. Copy the raw response data.
|
||||
|
||||
The XML obtained 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:
|
||||
|
||||
1. Copy all the attributes from `EntitiesDescriptor` to the `EntityDescriptor` that are not present.
|
||||
1. Remove the `<EntitiesDescriptor>` tag from the beginning.
|
||||
1. 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>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Keycloak 14+">
|
||||
|
||||
1. From the **Configure** section, click the **Realm Settings** tab.
|
||||
1. Click the **General** tab.
|
||||
1. From the **Endpoints** field, click **SAML 2.0 Identity Provider Metadata**.
|
||||
|
||||
Verify the IDP metadata contains the following attributes:
|
||||
|
||||
```
|
||||
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
|
||||
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
|
||||
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
||||
```
|
||||
|
||||
Some browsers, such as Firefox, may render/process the document such that the contents appear to have been modified, and some attributes appear to be missing. In this situation, use the raw response data that can be found using your browser.
|
||||
|
||||
The following is an example process for Firefox, but will vary slightly for other browsers:
|
||||
|
||||
1. Press **F12** to access the developer console.
|
||||
1. Click the **Network** tab.
|
||||
1. From the table, click the row containing `descriptor`.
|
||||
1. From the details pane, click the **Response** tab.
|
||||
1. Copy the raw response data.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Configuring Keycloak in Rancher
|
||||
|
||||
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **Keycloak SAML**.
|
||||
1. Complete the **Configure Keycloak Account** form. For help with filling the form, see the [configuration reference](#configuration-reference).
|
||||
1. After you complete the **Configure a Keycloak Account** form, click **Enable**.
|
||||
|
||||
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 >}}
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
| Field | Description |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Display Name Field | The attribute that contains the display name of users. <br/><br/>Example: `givenName` |
|
||||
| User Name Field | The attribute that contains the user name/given name. <br/><br/>Example: `email` |
|
||||
| UID Field | An attribute that is unique to every user. <br/><br/>Example: `email` |
|
||||
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `member` |
|
||||
| Entity ID Field | The ID that needs to be configured as a client ID in the Keycloak client. <br/><br/>Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` |
|
||||
| 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
|
||||
|
||||
## 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.6/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**, you 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.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: Local Authentication
|
||||
weight: 1111
|
||||
---
|
||||
|
||||
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. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Users**.
|
||||
1. Click **Create**.
|
||||
1. Complete the **Add User** form.
|
||||
1. Click **Create**.
|
||||
-82
@@ -1,82 +0,0 @@
|
||||
---
|
||||
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.6/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Configuring Microsoft Active Directory Federation Service (SAML)
|
||||
weight: 1205
|
||||
---
|
||||
|
||||
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.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
|
||||
- [2. Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)
|
||||
|
||||
{{< saml_caveats >}}
|
||||
|
||||
|
||||
### [Next: Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
|
||||
-45
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: 2. Configuring Rancher for Microsoft AD FS
|
||||
weight: 1205
|
||||
---
|
||||
|
||||
After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/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 ADFS 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. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **ADFS**.
|
||||
1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The [configuration section below](#configuration) describe how you can map AD attributes to fields within Rancher.
|
||||
1. After you complete the **Configure AD FS Account** form, click **Enable**.
|
||||
|
||||
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.
|
||||
|
||||
# Configuration
|
||||
|
||||
| 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,50 +0,0 @@
|
||||
---
|
||||
title: Configuring Okta (SAML)
|
||||
weight: 1210
|
||||
---
|
||||
|
||||
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. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **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 **Enable**.
|
||||
|
||||
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 >}}
|
||||
-86
@@ -1,86 +0,0 @@
|
||||
---
|
||||
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.6/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 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, they are 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.6/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. |
|
||||
| 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.6/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. |
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Configuring OpenLDAP
|
||||
weight: 1113
|
||||
---
|
||||
|
||||
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.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
|
||||
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **OpenLDAP**. Fill out the **Configure an OpenLDAP server** form.
|
||||
1. Click **Enable**.
|
||||
|
||||
### 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.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
|
||||
-52
@@ -1,52 +0,0 @@
|
||||
---
|
||||
title: Configuring PingIdentity (SAML)
|
||||
weight: 1200
|
||||
---
|
||||
|
||||
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. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **Ping Identity**.
|
||||
1. Complete the **Configure a 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. **Entity ID Field** (optional): The published, protocol-dependent, unique identifier of your partner. This ID defines your organization as the entity operating the server for SAML 2.0 transactions. This ID may have been obtained out-of-band or via a SAML metadata file.
|
||||
|
||||
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 **Enable**.
|
||||
|
||||
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 >}}
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Group Permissions with Shibboleth and OpenLDAP
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
title: Configuring Shibboleth (SAML)
|
||||
weight: 1210
|
||||
---
|
||||
|
||||
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. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **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 **Enable**.
|
||||
|
||||
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.6/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.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
|
||||
|
||||
1. Log into the Rancher UI using the initial local `admin` account.
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **Auth Provider**.
|
||||
1. Click **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.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
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.6/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.6/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. In the upper left corner, click **☰ > Users & Authentication**. In the left navigation bar, click **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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
To change these settings,
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Go to the setting you want to configure and click **⋮ > Edit 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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. On the **Users** page, 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
|
||||
|
||||
The default length (TTL) of each user session is adjustable. The default session length is 16 hours.
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Go to **`auth-user-session-ttl-minutes`** and click **⋮ > Edit Setting**.
|
||||
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.
|
||||
File diff suppressed because one or more lines are too long
@@ -1,130 +0,0 @@
|
||||
---
|
||||
title: Cluster Templates
|
||||
weight: 100
|
||||
---
|
||||
|
||||
Cluster templates encompass both Kubernetes configuration and node pool configuration, allowing a single template to contain all the information Rancher needs to provision new nodes in a cloud provider and install Kubernetes on those nodes.
|
||||
|
||||
- [Overview](#overview)
|
||||
- [RKE2 Cluster Template](#rke2-cluster-template)
|
||||
- [Adding a Cluster Template to Rancher](#adding-a-cluster-template-to-rancher)
|
||||
- [Creating a Cluster from a Cluster Template](#creating-a-cluster-from-a-cluster-template)
|
||||
- [Updating a Cluster Created from a Cluster Template](#updating-a-cluster-created-from-a-cluster-template)
|
||||
- [Deploying Clusters from a Template with Fleet](#deploying-clusters-from-a-template-with-fleet)
|
||||
- [Uninstalling Cluster Templates](#uninstalling-cluster-templates)
|
||||
- [Configuration Options](#configuration-options)
|
||||
|
||||
# Overview
|
||||
|
||||
Cluster templates are provided as Helm charts. To use them, you will need to clone and fork the templates, change them according to your use case, and then install the Helm charts on the Rancher management cluster. When the Helm chart is installed on the Rancher management cluster, a new cluster resource is created, which Rancher uses to provision the new cluster.
|
||||
|
||||
After the cluster is provisioned using the template, no changes to the template will affect the cluster. After the cluster is created from the cluster template, its configuration and infrastructure can change, because no restrictions are enforced by cluster templates.
|
||||
|
||||
### Kubernetes Distribution
|
||||
|
||||
Cluster templates can use any Kubernetes distribution. For now, we provide an example with an RKE2 Kubernetes cluster. We may provide more examples in the future using other Kubernetes distributions.
|
||||
|
||||
### Versioning
|
||||
|
||||
Rancher doesn't manage version control for cluster templates. Version control is handled in the repository containing the template's Helm chart.
|
||||
|
||||
# RKE2 Cluster Template
|
||||
|
||||
The example repository for an RKE2 cluster template is [here](https://github.com/rancher/cluster-template-examples). As of Rancher v2.6.0, we provide an RKE2 cluster template and may add more in the future.
|
||||
|
||||
# Adding a Cluster Template to Rancher
|
||||
|
||||
In this section, you'll learn how to add the cluster template to the `local` cluster's chart repo list. The result is that Rancher will include the cluster template as an option when users install new Kubernetes clusters.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - You will need permission to install Helm charts on the `local` Kubernetes cluster that Rancher is installed on.
|
||||
> - In order for the chart to appear in the form for creating new clusters, the chart must have the annotation `catalog.cattle.io/type: cluster-template`.
|
||||
|
||||
1. Go to a cluster template example repository. Rancher's examples are in [this GitHub repository.](https://github.com/rancher/cluster-template-examples) As of Rancher v2.6.0, we provide an RKE2 cluster template and add to more in the future.
|
||||
1. Fork the repository.
|
||||
1. Optional: Edit the cluster options by editing the `values.yaml` file. For help editing the file, see the cluster template's Helm chart README.
|
||||
1. Add the chart repository to Rancher. Click **☰ > Cluster Management**.
|
||||
1. Go to the `local` cluster and click **Explore.**
|
||||
1. In the left navigation bar, click **Apps & Marketplace > Chart Repositories.**
|
||||
1. Click **Create.**
|
||||
1. Enter a name for the cluster template repository.
|
||||
1. Click **Git Repository containing Helm chart definitions.**
|
||||
1. In the **Git Repo URL** field, enter the URL for the repository. For example, `https://github.com/rancher/cluster-template-examples.git`.
|
||||
1. In the **Git Branch** field, enter the branch to use as the source for the template. Rancher's example repository uses `main`.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The cluster template available from the **Apps & Marketplace** in Rancher's `local` cluster. It can now be used to deploy clusters.
|
||||
|
||||
> * **Restricted Admin access:** If you are a restricted admin and don’t have access to the `local` cluster, you may still add new RKE2 templates and manage cluster repositories. To navigate to the chart repository, go to the left navigation bar and click **☰ > Cluster Management > Advanced > Repositories**. You will bypass steps 1 - 6 above, then proceed to follow steps 7 - 12 to create the cluster template.
|
||||
|
||||
# Creating a Cluster from a Cluster Template
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - You will need permission to provision new Kubernetes clusters.
|
||||
> - You will need cloud credentials for provisioning infrastructure using the template.
|
||||
> - In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type: cluster-template` annotation.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, click **Create.**
|
||||
1. Click the name of your cluster template.
|
||||
1. Finish installing the Helm chart.
|
||||
|
||||
**Result:** After Rancher provisions the new cluster, it is managed in the same way as any other Rancher-launched Kubernetes cluster. You can configure any options through the UI if the cluster template has options for the user to choose from.
|
||||
|
||||
# Updating a Cluster Created from a Cluster Template
|
||||
|
||||
You can update any clusters using a template from the **Apps & Marketplace > Installed Apps** page, given there is a new version of a template being used by those clusters.
|
||||
|
||||
# Deploying Clusters from a Template with Fleet
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - You will need permission to provision new Kubernetes clusters.
|
||||
> - You will need cloud credentials for provisioning infrastructure using the template.
|
||||
> - In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type:cluster-template` annotation.
|
||||
> - In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the `fleet-local` namespace of the `local` cluster.
|
||||
> - All values must be set in the `values.yaml` of the template.
|
||||
> - Fleet repositories must follow the guidelines on [this page.](http://fleet.rancher.io/gitrepo-structure/) For RKE2 cluster templates, that means a `fleet.yaml` file must be added to the repository.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, click **Create.**
|
||||
1. Click **Create Cluster from Template.**
|
||||
|
||||
**Result:** After Rancher provisions the new cluster, it is managed by Fleet.
|
||||
|
||||
# Uninstalling Cluster Templates
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the `local` cluster and click **Apps & Marketplace > Chart Repositories.**
|
||||
1. Go to the chart repository for your cluster template and click **⋮ > Delete.**
|
||||
1. Confirm the deletion.
|
||||
|
||||
**Result:** The cluster template is uninstalled. This action does not affect clusters created with the cluster template.
|
||||
|
||||
An admin with access to the `local` cluster can also remove a cluster deployed via cluster templates through the **Apps & Marketplace > Installed Apps** page.
|
||||
|
||||
# Configuration Options
|
||||
|
||||
Cluster templates are flexible enough that they can be used to configure all of the following options:
|
||||
|
||||
- Node configuration
|
||||
- Node pools
|
||||
- Pre-specified cloud credentials
|
||||
- Enable/configure an authorized cluster endpoint to get kubectl access to the cluster without using Rancher as a proxy
|
||||
- Install Rancher V2 monitoring
|
||||
- Kubernetes version
|
||||
- Assign cluster members
|
||||
- Infrastructure configuration such as AWS VPC/subnets or vSphere data center
|
||||
- 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
|
||||
|
||||
For details on how to configure the template, refer to the cluster template's Helm chart README.
|
||||
-38
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Configuring a Global Default Private Registry
|
||||
weight: 40
|
||||
---
|
||||
|
||||
You might want to use a private container 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 container 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 installation guide]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap).
|
||||
|
||||
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](#setting-a-private-registry-with-credentials-when-deploying-a-cluster) 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. Click **☰ > Global Settings**.
|
||||
1. Go to the setting called `system-default-registry` and choose **⋮ > Edit Setting**.
|
||||
1. Change the value to your registry (e.g. `registry.yourdomain.com:port`). Do not prefix the registry with `http://` or `https://`.
|
||||
|
||||
**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 create a cluster:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, click **Create**.
|
||||
1. Choose a cluster type.
|
||||
1. In the **Cluster Configuration** go to the **Registries** tab and click **Pull images for Rancher from a private registry**.
|
||||
1. Enter the registry hostname and credentials.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The new cluster will be able to pull images from the private registry.
|
||||
|
||||
The private registry cannot be configured after the cluster is created.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Cluster Drivers
|
||||
weight: 1
|
||||
---
|
||||
|
||||
Cluster drivers are used to create clusters in a [hosted Kubernetes provider]({{<baseurl>}}/rancher/v2.6/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.6/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
|
||||
2. In the left navigation menu, click **Drivers**.
|
||||
|
||||
3. On the **Cluster Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.
|
||||
|
||||
## 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **Drivers**.
|
||||
1. On the **Cluster Drivers** tab, click **Add Cluster Driver**.
|
||||
1. 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).
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: Provisioning Drivers
|
||||
weight: 70
|
||||
---
|
||||
|
||||
Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.6/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.6/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.6/en/cluster-provisioning/hosted-kubernetes-clusters/eks/)
|
||||
* [Google GKE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/gke/)
|
||||
* [Azure AKS]({{<baseurl>}}/rancher/v2.6/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.6/en/cluster-provisioning/hosted-kubernetes-clusters/ack/)
|
||||
* [Huawei CCE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/cce/)
|
||||
* [Tencent]({{<baseurl>}}/rancher/v2.6/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.6/en/cluster-provisioning/rke-clusters/node-pools/ec2/)
|
||||
* [Azure]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/)
|
||||
* [Digital Ocean]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/)
|
||||
* [vSphere]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/)
|
||||
|
||||
There are several other node drivers that are disabled by default, but are packaged in Rancher:
|
||||
|
||||
* [Harvester]({{<baseurl>}}/rancher/v2.6/en/virtualization-admin/#harvester-node-driver/), available in Rancher v2.6.1
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
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.6/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
|
||||
2. In the left navigation menu, click **Drivers**.
|
||||
|
||||
2. On the **Node Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.
|
||||
|
||||
## 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **Drivers**.
|
||||
1. On **Node Drivers** tab, click **Add Node Driver**.
|
||||
1. 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/).
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
title: Upgrading Kubernetes without Upgrading Rancher
|
||||
weight: 30
|
||||
---
|
||||
|
||||
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.6/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.6/en/admin-settings/rbac/global-permissions/)
|
||||
|
||||
To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available:
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **Drivers**.
|
||||
1. Click **Refresh Kubernetes Metadata**.
|
||||
|
||||
You can configure Rancher to only refresh metadata when desired by setting `refresh-interval-minutes` to `0` (see below) and using this button to perform the metadata refresh manually when desired.
|
||||
|
||||
### 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.
|
||||
|
||||
To edit the metadata config in Rancher,
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Go to the **rke-metadata-config** section. Click **⋮ > Edit Setting**.
|
||||
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`.
|
||||
1. Click **Save**.
|
||||
|
||||
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.
|
||||
|
||||
### 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.6/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.
|
||||
-78
@@ -1,78 +0,0 @@
|
||||
---
|
||||
title: Pod Security Policies
|
||||
weight: 60
|
||||
---
|
||||
|
||||
_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...`.
|
||||
|
||||
- [How PSPs Work](#how-psps-work)
|
||||
- [Default PSPs](#default-psps)
|
||||
- [Restricted-NoRoot](#restricted-noroot)
|
||||
- [Restricted](#restricted)
|
||||
- [Unrestricted](#unrestricted)
|
||||
- [Creating PSPs](#creating-psps)
|
||||
- [Requirements](#requirements)
|
||||
- [Creating PSPs in the Rancher UI](#creating-psps-in-the-rancher-ui)
|
||||
- [Configuration](#configuration)
|
||||
|
||||
# How PSPs Work
|
||||
|
||||
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.
|
||||
|
||||
Read more about Pod Security Policies in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
|
||||
|
||||
# Default PSPs
|
||||
|
||||
Rancher ships with three default Pod Security Policies (PSPs): the `restricted-noroot`, `restricted` and `unrestricted` policies.
|
||||
|
||||
### Restricted-NoRoot
|
||||
|
||||
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.
|
||||
|
||||
### Restricted
|
||||
|
||||
This policy is a relaxed version of the `restricted-noroot` policy, with almost all the restrictions in place, except for the fact that it allows running containers as a privileged user.
|
||||
|
||||
### 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 PSPs
|
||||
|
||||
Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.
|
||||
|
||||
### Requirements
|
||||
|
||||
Rancher can only assign PSPs for clusters that are [launched using RKE]({{< baseurl >}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/).
|
||||
|
||||
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.6/en/cluster-admin/editing-clusters/).
|
||||
|
||||
It is a best practice to set PSP at the cluster level.
|
||||
|
||||
We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.
|
||||
|
||||
### Creating PSPs in the Rancher UI
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation bar, click **Pod Security Policies**.
|
||||
1. Click **Add Policy**.
|
||||
1. Name the policy.
|
||||
1. Complete each section of the form. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) for more information on what each policy does.
|
||||
1. Click **Create**.
|
||||
|
||||
# Configuration
|
||||
|
||||
The Kubernetes documentation on PSPs is [here](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
|
||||
-225
@@ -1,225 +0,0 @@
|
||||
---
|
||||
title: Cluster and Project Roles
|
||||
weight: 1127
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Cluster and project roles define user authorization inside a cluster or project.
|
||||
|
||||
To manage these roles,
|
||||
|
||||
1. Click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles** and go to the **Cluster** or **Project/Namespaces** tab.
|
||||
|
||||
### 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 [(see table below)](#Manage-Nodes-Permissions)| ✓ | |
|
||||
| Manage Storage | ✓ | |
|
||||
| View All Projects | ✓ | |
|
||||
| View Cluster Catalogs | ✓ | ✓ |
|
||||
| View Cluster Members | ✓ | ✓ |
|
||||
| View Nodes | ✓ | ✓ |
|
||||
|
||||
#### Manage Nodes Permissions
|
||||
|
||||
The following table lists the permissions available for the `Manage Nodes` role in RKE and RKE2.
|
||||
|
||||
| Manage Nodes Permissions | RKE | RKE2 |
|
||||
|-----------------------------|-------- |--------- |
|
||||
| SSH Access | ✓ | ✓ |
|
||||
| Delete Nodes | ✓ | ✓ |
|
||||
| Scale Clusters Up and Down | ✓ | * |
|
||||
***In RKE2, you must have permission to edit a cluster to be able to scale clusters up and down.**
|
||||
<br />
|
||||
|
||||
For details on how each cluster role can access Kubernetes resources, you can look them up in the Rancher UI:
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Click the **Cluster** tab.
|
||||
1. Click the name of an individual role. The table shows 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.6/en/admin-settings/rbac/default-custom-roles/) 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,
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster where you want to assign a role to a member and click **Explore**.
|
||||
1. Click **RBAC > Cluster Members**.
|
||||
1. Click **Add**.
|
||||
1. In the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member.
|
||||
1. Click **Create**.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster where you want to assign a role to a member and click **Explore**.
|
||||
1. Click **Cluster > Cluster Members**.
|
||||
1. Click **Add**.
|
||||
1. In the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member.
|
||||
1. Click **Create**.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
**Result:** The member has the assigned role.
|
||||
|
||||
To assign any custom role to an existing cluster member,
|
||||
|
||||
1. Click **☰ > Users & Authentication**.
|
||||
1. Go to the member you want to give the role to. Click the **⋮ > Edit Config**.
|
||||
1. If you have added custom roles, they will show in the **Custom** section. Choose the role you want to assign to the member.
|
||||
1. Click **Save**.
|
||||
|
||||
**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.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces.
|
||||
|
||||
- **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 Secrets | ✓ | ✓ | |
|
||||
| View Config Maps | ✓ | ✓ | ✓ |
|
||||
| View Ingress | ✓ | ✓ | ✓ |
|
||||
| View Project Members | ✓ | ✓ | ✓ |
|
||||
| View Project Catalogs | ✓ | ✓ | ✓ |
|
||||
| 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.6/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.6/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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Click the **Cluster** or **Project/Namespaces** tab.
|
||||
1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **⋮ > Edit Config**.
|
||||
1. In the **Cluster Creator Default** or **Project Creator Default** section, enable the role as the default.
|
||||
1. Click **Save**.
|
||||
|
||||
**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.
|
||||
|
||||
If you want to remove a default role, edit the permission and select **No** from the default roles option.
|
||||
|
||||
### 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.
|
||||
-121
@@ -1,121 +0,0 @@
|
||||
---
|
||||
title: Custom Roles
|
||||
weight: 1128
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
> It is possible for a custom role to enable privilege escalation. For details, see [this section.](#privilege-escalation)
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Creating a custom role](#creating-a-custom-role)
|
||||
- [Creating a custom role that inherits from another role](#creating-a-custom-role-that-inherits-from-another-role)
|
||||
- [Deleting a custom role](#deleting-a-custom-role)
|
||||
- [Assigning a custom role to a group](#assigning-a-custom-role-to-a-group)
|
||||
- [Privilege escalation](#privilege-escalation)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
To complete the tasks on this page, one of the following permissions are required:
|
||||
|
||||
- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/).
|
||||
- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned.
|
||||
|
||||
# Creating A Custom Role
|
||||
|
||||
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.
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Select a tab to determine the scope of the role you're adding. The tabs are:
|
||||
|
||||
- **Global:** The role is valid for allowing members to manage global scoped resources.
|
||||
- **Cluster:** The role is valid for assignment when adding/managing members to clusters.
|
||||
- **Project/Namespaces:** The role is valid for assignment when adding/managing members to projects or namespaces.
|
||||
|
||||
1. Click **Create Global Role,** **Create Cluster Role** or **Create Project/Namespaces Role,** depending on the scope.
|
||||
1. Enter a **Name** for 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.
|
||||
|
||||
> The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field.
|
||||
|
||||
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** 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**.
|
||||
|
||||
# Creating a Custom Role that Inherits from Another 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 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 role can then be assigned to a user or group so that the role takes effect the first time the user or users sign into Rancher.
|
||||
|
||||
To create a custom role based on an existing role,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Click the **Cluster** or **Project/Namespaces** tab. Click **Create Cluster Role** or **Create Project/Namespaces Role** depending on the scope. Note: Only cluster roles and project/namespace roles can inherit from another role.
|
||||
1. Enter a name for the role.
|
||||
1. In the **Inherit From** tab, select the role(s) that the custom role will inherit permissions from.
|
||||
1. In the **Grant Resources** tab, select the Kubernetes resource operations that will be enabled for users with the custom role.
|
||||
|
||||
> The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field.
|
||||
1. Optional: Assign the role as default.
|
||||
1. Click **Create**.
|
||||
|
||||
# Deleting a Custom Role
|
||||
|
||||
When deleting a custom role, all global role bindings with this custom role are deleted.
|
||||
|
||||
If a user is only assigned one custom 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 roles can be deleted, but built-in roles cannot be deleted.
|
||||
|
||||
To delete a custom role,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
2. Go to the custom global role that should be deleted and click **⋮ (…) > Delete**.
|
||||
3. Click **Delete**.
|
||||
|
||||
# Assigning a Custom Role to a Group
|
||||
|
||||
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom 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 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.6/en/admin-settings/authentication/#external-vs-local-authentication)
|
||||
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/user-groups/)
|
||||
> * You have already set up at least one user group with the authentication provider
|
||||
|
||||
To assign a custom role to a group, follow these steps:
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Groups**.
|
||||
1. Go to the existing group that will be assigned the custom role and click **⋮ > Edit Config**.
|
||||
1. If you have created roles, they will show in the **Custom** section. Choose any custom 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 **Save.**.
|
||||
|
||||
**Result:** The custom role will take effect when the users in the group log into Rancher.
|
||||
|
||||
# Privilege Escalation
|
||||
|
||||
The `Configure Catalogs` custom permission is powerful and should be used with caution. When an admin assigns the `Configure Catalogs` permission to a standard user, it could result in privilege escalation in which the user could give themselves admin access to Rancher provisioned clusters. Anyone with this permission should be considered equivalent to an admin.
|
||||
-254
@@ -1,254 +0,0 @@
|
||||
---
|
||||
title: Global Permissions
|
||||
weight: 1126
|
||||
---
|
||||
|
||||
_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 four default global permissions: `Administrator`, `Restricted Admin`,`Standard User` and `User-base`.
|
||||
|
||||
- **Administrator:** These users have full control over the entire Rancher system and all clusters within it.
|
||||
|
||||
- **Restricted Admin:** These users have full control over downstream clusters, but cannot alter the local Kubernetes cluster.
|
||||
|
||||
- <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:
|
||||
|
||||
- [Restricted Admin](#restricted-admin)
|
||||
- [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)
|
||||
|
||||
# Restricted Admin
|
||||
|
||||
A new `restricted-admin` role was created in Rancher v2.5 in order to prevent privilege escalation from the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster.
|
||||
|
||||
The `restricted-admin` can create other `restricted-admin` users with an equal level of access.
|
||||
|
||||
A new setting was added to Rancher to set the initial bootstrapped administrator to have the `restricted-admin` role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.
|
||||
|
||||
To bootstrap Rancher with the `restricted-admin` as the initial user, the Rancher server should be started with the following environment variable:
|
||||
|
||||
```
|
||||
CATTLE_RESTRICTED_DEFAULT_ADMIN=true
|
||||
```
|
||||
### List of `restricted-admin` Permissions
|
||||
|
||||
The following table lists the permissions and actions that a `restricted-admin` should have in comparison with the `Administrator` and `Standard User` roles:
|
||||
|
||||
| Category | Action | Global Admin | Standard User | Restricted Admin | Notes for Restricted Admin role |
|
||||
| -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- |
|
||||
| Local Cluster functions | Manage Local Cluster (List, Edit, Import Host) | Yes | No | No | |
|
||||
| | Create Projects/namespaces | Yes | No | No | |
|
||||
| | Add cluster/project members | Yes | No | No | |
|
||||
| | Deploy MulticlusterApp in local cluster | Yes | No | No | |
|
||||
| | Global DNS | Yes | No | No | |
|
||||
| | Access to management cluster for CRDs and CRs | Yes | No | Yes | |
|
||||
| | Save as RKE Template | Yes | No | No | |
|
||||
| Security | | | | | |
|
||||
| Enable auth | Configure Authentication | Yes | No | Yes | |
|
||||
| Roles | Create/Assign GlobalRoles | Yes | No (Can list) | Yes | Auth webhook allows creating globalrole for perms already present |
|
||||
| | Create/Assign ClusterRoles | Yes | No (Can list) | Yes | Not in local cluster |
|
||||
| | Create/Assign ProjectRoles | Yes | No (Can list) | Yes | Not in local cluster |
|
||||
| Users | Add User/Edit/Delete/Deactivate User | Yes | No | Yes | |
|
||||
| Groups | Assign Global role to groups | Yes | No | Yes | As allowed by the webhook |
|
||||
| | Refresh Groups | Yes | No | Yes | |
|
||||
| PSP's | Manage PSP templates | Yes | No (Can list) | Yes | Same privileges as Global Admin for PSPs |
|
||||
| Tools | | | | | |
|
||||
| | Manage RKE Templates | Yes | No | Yes | |
|
||||
| | Manage Global Catalogs | Yes | No | Yes | Cannot edit/delete built-in system catalog. Can manage Helm library |
|
||||
| | Cluster Drivers | Yes | No | Yes | |
|
||||
| | Node Drivers | Yes | No | Yes | |
|
||||
| | GlobalDNS Providers | Yes | Yes (Self) | Yes | |
|
||||
| | GlobalDNS Entries | Yes | Yes (Self) | Yes | |
|
||||
| Settings | | | | | |
|
||||
| | Manage Settings | Yes | No (Can list) | No (Can list) | |
|
||||
| Apps | | | | | |
|
||||
| | Launch Multicluster Apps | Yes | Yes | Yes | Not in local cluster |
|
||||
| User | | | | | |
|
||||
| | Manage API Keys | Yes (Manage all) | Yes (Manage self) | Yes (Manage self) | |
|
||||
| | Manage Node Templates | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own node templates and not those created by other users |
|
||||
| | Manage Cloud Credentials | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own cloud credentials and not those created by other users |
|
||||
| Downstream Cluster | Create Cluster | Yes | Yes | Yes | |
|
||||
| | Edit Cluster | Yes | Yes | Yes | |
|
||||
| | Rotate Certificates | Yes | | Yes | |
|
||||
| | Snapshot Now | Yes | | Yes | |
|
||||
| | Restore Snapshot | Yes | | Yes | |
|
||||
| | Save as RKE Template | Yes | No | Yes | |
|
||||
| | Run CIS Scan | Yes | Yes | Yes | |
|
||||
| | Add Members | Yes | Yes | Yes | |
|
||||
| | Create Projects | Yes | Yes | Yes | |
|
||||
| Feature Charts since v2.5 | | | | | |
|
||||
| | Install Fleet | Yes | | Yes | Should not be able to run Fleet in local cluster |
|
||||
| | Deploy EKS cluster | Yes | Yes | Yes | |
|
||||
| | Deploy GKE cluster | Yes | Yes | Yes | |
|
||||
| | Deploy AKS cluster | Yes | Yes | Yes | |
|
||||
|
||||
|
||||
### Changing Global Administrators to Restricted Admins
|
||||
|
||||
If Rancher already has a global administrator, they should change all global administrators over to the new `restricted-admin` role.
|
||||
|
||||
This can be done through **Security > Users** and moving any Administrator role over to Restricted Administrator.
|
||||
|
||||
Signed-in users can change themselves over to the `restricted-admin` if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.
|
||||
|
||||
# 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,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. The **Roles** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **Global** tab, in the **New User Default** column, the permissions given to new users by default are indicated with a checkmark.
|
||||
|
||||
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,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. The **Roles** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **New User Default** column on each page, the permissions given to new users by default are indicated with a checkmark.
|
||||
|
||||
You can [change the default permissions 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)
|
||||
|
||||
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.6/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)
|
||||
- [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users)
|
||||
- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
|
||||
|
||||
### 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) | ✓ | ✓ | |
|
||||
|
||||
For details on which Kubernetes resources correspond to each global permission,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. If you click the name of an individual role, a table shows 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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**. On the **Roles** page, 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 **⋮ > Edit Config**.
|
||||
1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**. If you want to remove a default permission, edit the permission and select **No**.
|
||||
|
||||
**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 Individual Users
|
||||
|
||||
To configure permission for a user,
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Users**.
|
||||
1. Go to the user whose access level you want to change and click **⋮ > Edit Config**.
|
||||
1. In the **Global Permissions** and **Built-in** sections, check the boxes for each permission you want the user to have. If you have created roles from the **Roles** page, they will appear in the **Custom** section and you can choose from them as well.
|
||||
1. Click **Save**.
|
||||
|
||||
> **Result:** The user's global permissions have been updated.
|
||||
|
||||
### Configuring Global Permissions for Groups
|
||||
|
||||
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.6/en/admin-settings/authentication/#external-vs-local-authentication)
|
||||
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.6/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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Groups**.
|
||||
1. Go to the group you want to assign a custom global role to and click **⋮ > Edit Config**.
|
||||
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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Users**.
|
||||
1. Click **Refresh Group Memberships**.
|
||||
|
||||
**Result:** Any changes to the group members' permissions will take effect.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Locked Roles
|
||||
weight: 1129
|
||||
---
|
||||
|
||||
You can set roles to a status of `locked`. Locking roles prevent them from being assigned to 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.6/en/admin-settings/rbac/default-custom-roles/).
|
||||
- When you editing an existing role (see below).
|
||||
|
||||
Cluster roles and project/namespace roles can be locked, but global roles cannot.
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Go to the **Cluster** tab or the **Project/Namespaces** tab.
|
||||
1. From the role that you want to lock (or unlock), select **⋮ > Edit Config**.
|
||||
1. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**.
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: Role-Based Access Control (RBAC)
|
||||
weight: 20
|
||||
---
|
||||
|
||||
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.6/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.6/en/admin-settings/rbac/global-permissions/):
|
||||
|
||||
Define user authorization outside the scope of any particular cluster.
|
||||
|
||||
- [Cluster and Project Roles]({{<baseurl>}}/rancher/v2.6/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.
|
||||
-61
@@ -1,61 +0,0 @@
|
||||
---
|
||||
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.6/en/admin-settings/rke-templates/template-access-and-sharing)
|
||||
|
||||
RKE templates can be applied to new clusters.
|
||||
|
||||
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.6/en/cluster-provisioning/rke-clusters) using an RKE template, use these steps:
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, click **Create** 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 RKE 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 **Create** 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.6/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.
|
||||
|
||||
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
|
||||
|
||||
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.6/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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster that will be converted to use an RKE template. Click **⋮ > 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.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
|
||||
-171
@@ -1,171 +0,0 @@
|
||||
---
|
||||
title: Creating and Revising RKE Templates
|
||||
weight: 32
|
||||
---
|
||||
|
||||
This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the **Cluster Management** view under **RKE1 Configuration > 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.6/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.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
|
||||
|
||||
### Creating a Template
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Click **RKE1 configuration > Node 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.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users-or-groups) 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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
|
||||
1. Go to the template that you want to edit and click the **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Click **RKE1 configuration > RKE Templates**.
|
||||
1. Go to the RKE template that you want to delete and click the **⋮ > Delete**.
|
||||
1. Confirm the deletion.
|
||||
|
||||
**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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
|
||||
1. Go to the RKE template that you want to clone and click the **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Under **RKE1 configuration**, click **RKE Templates**.
|
||||
1. Go to the template revision you want to clone. Then select **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
|
||||
1. Go to the template revision you want to disable. Then select **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Under **RKE1 configuration**, click **RKE Templates**.
|
||||
1. Go to the template revision you want to re-enable. Then select **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE templates**.
|
||||
1. Go to the RKE template revision that should be default and click the **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE templates**.
|
||||
1. Go to the RKE template revision that should be deleted and click the **⋮ > 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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you want to upgrade and click **⋮ > Edit Config**.
|
||||
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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that will be converted to use an RKE template and **⋮ > Save as RKE Template**.
|
||||
1. Enter a name for the RKE 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.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
---
|
||||
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.6/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.6/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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Users**.
|
||||
1. Choose the user you want to edit and click **⋮ > Edit Config**.
|
||||
1. In the **Built-in** section, check the box for **Create new RKE Cluster Templates** role along with any other roles the user should have. You may want to also check the box for **Create RKE Template Revisions**.
|
||||
1. 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. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Roles**.
|
||||
1. Go to the role named **Create new RKE Cluster Templates and click **⋮ > Edit Config**.
|
||||
1. Select the option **Yes: Default role for new users**.
|
||||
1. Click **Save**.
|
||||
1. If you would like new users to also be able to create RKE template revisions, enable that role as default as well.
|
||||
|
||||
**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. Note: Administrators have full control over all resources regardless of whether fine-grained permissions are selected.
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation bar, click **Users**.
|
||||
1. Choose the user you want to edit permissions for and click **⋮ > Edit Config**.
|
||||
1. In the **Built-in** section, un-check the box for **Create RKE Templates** and **Create RKE Template Revisions,** if applicable. In this section, you can change the user back to a standard user, or give the user a different set of permissions.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The user cannot create RKE templates.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
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.6/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.6/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.6/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.6/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. Click **☰ > Global Settings**.
|
||||
1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**.
|
||||
1. Set the value to **True** and click **Save**.
|
||||
|
||||
>**Important:** When the admin sets the `cluster-template-enforcement` to <b>True</b>, they also need to share the `clusterTemplates` with users so that users can select one of these templates to create the cluster.
|
||||
|
||||
**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. Click **☰ > Global Settings**.
|
||||
1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**.
|
||||
1. Set the value to **False** and click **Save**.
|
||||
|
||||
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
|
||||
-71
@@ -1,71 +0,0 @@
|
||||
---
|
||||
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.6/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.6/en/admin-settings/rke-templates/enforcement/#requiring-new-clusters-to-use-an-rke-template) This means that every [standard user]({{<baseurl>}}/rancher/v2.6/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.6/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.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) when the best practices change
|
||||
- [Disable outdated revisions]({{<baseurl>}}/rancher/v2.6/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.6/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.6/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.6/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.
|
||||
@@ -1,112 +0,0 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
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.6/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
|
||||
-70
@@ -1,70 +0,0 @@
|
||||
---
|
||||
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.6/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.6/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.
|
||||
@@ -1,127 +0,0 @@
|
||||
---
|
||||
title: RKE Templates
|
||||
weight: 80
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
You can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.6/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.6/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.
|
||||
|
||||
The settings of an existing cluster can be [saved as an RKE template.]({{<baseurl>}}/rancher/v2.6/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.6/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.6/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.6/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.6/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.6/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.6/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.6/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.6/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 **Cluster Management** view under **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.6/en/admin-settings/rke-templates/creator-permissions/)
|
||||
- [Creating and revising templates]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/)
|
||||
- [Enforcing template settings](./enforcement/#requiring-new-clusters-to-use-an-rke-template)
|
||||
- [Overriding template settings]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/overrides/)
|
||||
- [Sharing templates with cluster creators]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users-or-groups)
|
||||
- [Sharing ownership of a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
|
||||
|
||||
An [example YAML configuration file for a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-yaml) is provided for reference.
|
||||
|
||||
# Applying Templates
|
||||
|
||||
You can [create a cluster from a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template) that you created, or from a template that has been [shared with you.]({{<baseurl>}}/rancher/v2.6/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.6/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.
|
||||
|
||||
You can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.6/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, one option is to use RKE templates [in conjunction with other tools]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/rke-templates-and-hardware).
|
||||
|
||||
Another option is to use [cluster templates,]({{<baseurl>}}/rancher/v2.6/en/admin-settings/cluster-templates) which include node pool configuration options, but don't provide configuration enforcement.
|
||||
|
||||
# YAML Customization
|
||||
|
||||
If you define an RKE template as a YAML file, you can modify this [example RKE template YAML]({{<baseurl>}}/rancher/v2.6/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/)
|
||||
-65
@@ -1,65 +0,0 @@
|
||||
---
|
||||
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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Under **RKE1 configuration**, click **RKE Templates**.
|
||||
1. Go to the template that you want to share and click the **⋮ > 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
|
||||
1. Go to the template that you want to share and click the **⋮ > Edit**.
|
||||
1. Under **Share Template,** check the box for **Make Public (read-only)**.
|
||||
1. 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Under **RKE1 configuration**, click **RKE Templates**.
|
||||
1. Go to the RKE template that you want to share and click the **⋮ > 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.
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
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.
|
||||
|
||||
### Deleting tokens
|
||||
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) |
|
||||
|
||||
|
||||
### Setting TTL on Kubeconfig Tokens
|
||||
|
||||
Admins can set a global TTL on Kubeconfig tokens. Once the token expires the kubectl command will require the user to authenticate to Rancher.
|
||||
|
||||
Go to the global settings and:
|
||||
|
||||
1. Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. The kubeconfig file will now provide a command to login to Rancher.
|
||||
|
||||
_**Note:**_ Once this setting is deactivated, a generated kubeconfig will reference the [Rancher CLI]({{<baseurl>}}/rancher/v2.6/en/cli) to retrieve a short lived token for the cluster. When you use this kubeconfig in a client, such as `kubectl`, the Rancher CLI needs to be installed as well.
|
||||
|
||||
2. Set the `kubeconfig-token-ttl-minutes` setting to the desired duration in minutes. By default, `kubeconfig-token-ttl-minutes` is 960 (16 hours).
|
||||
|
||||
_**Note:**_ This value cannot exceed max-ttl of API tokens.(`https://<Rancher-Server-IP/v3/settings/auth-token-max-ttl-minutes`). `auth-token-max-ttl-minutes` is set to 1440 (24 hours) by default. `auth-token-max-ttl-minutes would default to 0 allowing tokens to never expire`.
|
||||
|
||||
### Token Hashing
|
||||
|
||||
Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluated in a test environment first.
|
||||
|
||||
To enable token hashing, refer to [this section]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags).
|
||||
|
||||
This feature will affect all tokens which include, but are not limited to, the following:
|
||||
|
||||
- Kubeconfig tokens
|
||||
- Bearer tokens API keys/calls
|
||||
- Tokens used by internal operations
|
||||
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: API
|
||||
weight: 24
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## 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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.6.4+">
|
||||
|
||||
1. Click on your user avatar in the upper right corner.
|
||||
1. Click **Account & API Keys**.
|
||||
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link will look something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.6.4">
|
||||
|
||||
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Authentication
|
||||
|
||||
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys]({{<baseurl>}}/rancher/v2.6/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.6/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.6/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.
|
||||
|
||||
## Capturing Rancher API Calls
|
||||
|
||||
You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:
|
||||
|
||||
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
|
||||
1. Click one of the cluster types. This example uses Digital Ocean.
|
||||
1. Fill out the form with a cluster name and node template, but don't click **Create**.
|
||||
1. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click **Inspect.**
|
||||
1. In the developer tools, click the **Network** tab.
|
||||
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
|
||||
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
|
||||
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
|
||||
1. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials.
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
title: Backing up Rancher
|
||||
weight: 1
|
||||
---
|
||||
|
||||
In this section, you'll learn how to back up Rancher running on any Kubernetes cluster. To backup Rancher installed with Docker, refer the instructions for [single node backups]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/docker-backups)
|
||||
|
||||
The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.
|
||||
|
||||
Note that the rancher-backup operator version 2.x.x is for Rancher v2.6.x.
|
||||
|
||||
> When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
The Rancher version must be v2.5.0 and up.
|
||||
|
||||
Refer [here]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher/#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3.
|
||||
|
||||
### 1. Install the Rancher Backups operator
|
||||
|
||||
The backup storage location is an operator-level setting, so it needs to be configured when the Rancher Backups application is installed or upgraded.
|
||||
|
||||
Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, or they can be stored in a persistent volume.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the `local` cluster and click **Explore**. The `local` cluster runs the Rancher server.
|
||||
1. Click **Apps & Marketplace > Charts**.
|
||||
1. Click **Rancher Backups**.
|
||||
1. Click **Install**.
|
||||
1. Configure the default storage location. For help, refer to the [storage configuration section.](../configuration/storage-config)
|
||||
1. Click **Install**.
|
||||
|
||||
>**NOTE:** There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{<baseurl>}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround.
|
||||
|
||||
### 2. Perform a Backup
|
||||
|
||||
To perform a backup, a custom resource of type Backup must be created.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the `local` cluster and click **Explore**.
|
||||
1. In the left navigation bar, click **Rancher Backups > Backups**.
|
||||
1. Click **Create**.
|
||||
1. Create the Backup with the form, or with the YAML editor.
|
||||
1. For configuring the Backup details using the form, click **Create** and refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup)
|
||||
1. For using the YAML editor, we can click **Create > Create from YAML**. Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3. The app uses the `credentialSecretNamespace` value to determine where to look for the S3 backup secret:
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-recurring-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
> **Note:** When creating the Backup resource using YAML editor, the `resourceSetName` must be set to `rancher-resource-set`
|
||||
|
||||
For help configuring the Backup, refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup)
|
||||
|
||||
> **Important:** The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore.
|
||||
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
title: Backups and Disaster Recovery
|
||||
weight: 5
|
||||
---
|
||||
|
||||
In this section, you'll learn how to create backups of Rancher, how to restore Rancher from backup, and how to migrate Rancher to a new Kubernetes cluster.
|
||||
|
||||
The `rancher-backup` operator is used to backup and restore Rancher on any Kubernetes cluster. This application is a Helm chart, and it can be deployed through the Rancher **Apps & Marketplace** page, or by using the Helm CLI. The `rancher-backup` Helm chart is [here.](https://github.com/rancher/charts/tree/release-v2.6/charts/rancher-backup)
|
||||
|
||||
The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.
|
||||
|
||||
- [Backup and Restore for Rancher installed with Docker](#backup-and-restore-for-rancher-installed-with-docker)
|
||||
- [How Backups and Restores Work](#how-backups-and-restores-work)
|
||||
- [Installing the rancher-backup Operator](#installing-the-rancher-backup-operator)
|
||||
- [Installing rancher-backup with the Rancher UI](#installing-rancher-backup-with-the-rancher-ui)
|
||||
- [Installing rancher-backup with the Helm CLI](#installing-rancher-backup-with-the-helm-cli)
|
||||
- [RBAC](#rbac)
|
||||
- [Backing up Rancher](#backing-up-rancher)
|
||||
- [Restoring Rancher](#restoring-rancher)
|
||||
- [Migrating Rancher to a New Cluster](#migrating-rancher-to-a-new-cluster)
|
||||
- [Default Storage Location Configuration](#default-storage-location-configuration)
|
||||
- [Example values.yaml for the rancher-backup Helm Chart](#example-values-yaml-for-the-rancher-backup-helm-chart)
|
||||
|
||||
# Backup and Restore for Rancher installed with Docker
|
||||
|
||||
For Rancher installed with Docker, refer to [this page](./docker-installs/docker-backups) to perform backups and [this page](./docker-installs/docker-restores) to perform restores.
|
||||
|
||||
# How Backups and Restores Work
|
||||
|
||||
The `rancher-backup` operator introduces three custom resources: Backups, Restores, and ResourceSets. The following cluster-scoped custom resource definitions are added to the cluster:
|
||||
|
||||
- `backups.resources.cattle.io`
|
||||
- `resourcesets.resources.cattle.io`
|
||||
- `restores.resources.cattle.io`
|
||||
|
||||
The ResourceSet defines which Kubernetes resources need to be backed up. The ResourceSet is not available to be configured in the Rancher UI because the values required to back up Rancher are predefined. This ResourceSet should not be modified.
|
||||
|
||||
When a Backup custom resource is created, the `rancher-backup` operator calls the `kube-apiserver` to get the resources in the ResourceSet (specifically, the predefined `rancher-resource-set`) that the Backup custom resource refers to.
|
||||
|
||||
The operator then creates the backup file in the .tar.gz format and stores it in the location configured in the Backup resource.
|
||||
|
||||
When a Restore custom resource is created, the operator accesses the backup .tar.gz file specified by the Restore, and restores the application from that file.
|
||||
|
||||
The Backup and Restore custom resources can be created in the Rancher UI, or by using `kubectl apply`.
|
||||
|
||||
>**Note:** Refer [here]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher/#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3.
|
||||
|
||||
# Installing the rancher-backup Operator
|
||||
|
||||
The `rancher-backup` operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the `rancher-backup` Helm chart is installed on the Kubernetes cluster running the Rancher server. It is a cluster-admin only feature and available only for the **local** cluster. (*If you do not see `rancher-backup` in the Rancher UI, you may have selected the wrong cluster.*)
|
||||
|
||||
>**NOTE:** There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{<baseurl>}}rancher/v2.6/en/deploy-across-clusters/fleet/#troubleshooting) for a workaround.
|
||||
|
||||
### Installing rancher-backup with the Rancher UI
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the `local` cluster and click **Explore**.
|
||||
1. In the left navigation bar, **Apps & Marketplace > Charts**.
|
||||
1. Click **Rancher Backups**.
|
||||
1. Click **Install**.
|
||||
1. Optional: Configure the default storage location. For help, refer to the [configuration section.](./configuration/storage-config)
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** The `rancher-backup` operator is installed.
|
||||
|
||||
From the **Cluster Dashboard,** you can see the `rancher-backup` operator listed under **Deployments**.
|
||||
|
||||
To configure the backup app in Rancher, go to the left navigation menu and click **Rancher Backups**.
|
||||
|
||||
### RBAC
|
||||
|
||||
Only the rancher admins and the local cluster’s cluster-owner can:
|
||||
|
||||
* Install the Chart
|
||||
* See the navigation links for Backup and Restore CRDs
|
||||
* Perform a backup or restore by creating a Backup CR and Restore CR respectively
|
||||
* List backups/restores performed so far
|
||||
|
||||
# Backing up Rancher
|
||||
|
||||
A backup is performed by creating a Backup custom resource. For a tutorial, refer to [this page.](./back-up-rancher)
|
||||
|
||||
# Restoring Rancher
|
||||
|
||||
A restore is performed by creating a Restore custom resource. For a tutorial, refer to [this page.](./restoring-rancher)
|
||||
|
||||
# Migrating Rancher to a New Cluster
|
||||
|
||||
A migration is performed by following [these steps.]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher)
|
||||
|
||||
# Default Storage Location Configuration
|
||||
|
||||
Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible or Minio object store.
|
||||
|
||||
For information on configuring these options, refer to [this page.](./configuration/storage-config)
|
||||
|
||||
### Example values.yaml for the rancher-backup Helm Chart
|
||||
|
||||
The example [values.yaml file](./configuration/storage-config/#example-values-yaml-for-the-rancher-backup-helm-chart) can be used to configure the `rancher-backup` operator when the Helm CLI is used to install it.
|
||||
@@ -1,176 +0,0 @@
|
||||
---
|
||||
title: Backup Configuration
|
||||
shortTitle: Backup
|
||||
weight: 1
|
||||
---
|
||||
|
||||
The Backup Create page lets you configure a schedule, enable encryption and specify the storage location for your backups.
|
||||
|
||||
- [Schedule](#schedule)
|
||||
- [Encryption](#encryption)
|
||||
- [Storage Location](#storage-location)
|
||||
- [S3](#s3)
|
||||
- [Example S3 Storage Configuration](#example-s3-storage-configuration)
|
||||
- [Example MinIO Configuration](#example-minio-configuration)
|
||||
- [Example credentialSecret](#example-credentialsecret)
|
||||
- [IAM Permissions for EC2 Nodes to Access S3](#iam-permissions-for-ec2-nodes-to-access-s3)
|
||||
- [Examples](#examples)
|
||||
|
||||
# Schedule
|
||||
|
||||
Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting **Recurring Backups** lets you configure following two fields:
|
||||
|
||||
- **Schedule**: This field accepts
|
||||
- Standard [cron expressions](https://en.wikipedia.org/wiki/Cron), such as `"0 * * * *"`
|
||||
- Descriptors, such as `"@midnight"` or `"@every 1h30m"`
|
||||
- **Retention Count**: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10.
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `schedule` | Provide the cron string for scheduling recurring backups. |
|
||||
| `retentionCount` | Provide the number of backup files to be retained. |
|
||||
|
||||
# Encryption
|
||||
|
||||
The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if [encryption At rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) is enabled, even the encrypted objects gathered by the backup will be in plaintext.
|
||||
|
||||
To avoid storing them in plaintext, you can use the same encryptionConfig file that was used for at-rest encryption, to encrypt certain resources in your backup.
|
||||
|
||||
> **Important:** You must save the encryptionConfig file, because it won’t be saved by the rancher-backup operator.
|
||||
The same encryptionFile needs to be used when performing a restore.
|
||||
|
||||
The operator consumes this encryptionConfig as a Kubernetes Secret, and the Secret must be in the operator’s namespace. Rancher installs the `rancher-backup` operator in the `cattle-resources-system` namespace, so create this encryptionConfig secret in that namespace.
|
||||
|
||||
For the `EncryptionConfiguration`, you can use the [sample file provided in the Kubernetes documentation.](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#understanding-the-encryption-at-rest-configuration)
|
||||
|
||||
To create the Secret, the encryption configuration file must be named `encryption-provider-config.yaml`, and the `--from-file` flag must be used to create this secret.
|
||||
|
||||
Save the `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command:
|
||||
|
||||
```
|
||||
kubectl create secret generic encryptionconfig \
|
||||
--from-file=./encryption-provider-config.yaml \
|
||||
-n cattle-resources-system
|
||||
```
|
||||
|
||||
This will ensure that the secret contains a key named `encryption-provider-config.yaml`, and the operator will use this key to get the encryption configuration.
|
||||
|
||||
The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key
|
||||
|
||||
{{< img "/img/rancher/backup_restore/backup/encryption.png" "">}}
|
||||
|
||||
In the example command above, the name `encryptionconfig` can be changed to anything.
|
||||
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. |
|
||||
|
||||
# Storage Location
|
||||
|
||||
If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the `rancher-backup` operator.
|
||||
|
||||
Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup.
|
||||
|
||||
### S3
|
||||
|
||||
The S3 storage location contains the following configuration fields:
|
||||
|
||||
1. **Credential Secret** (optional): If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives `accessKey` and `secretKey`. It can be in any namespace. An example secret is [here.](#example-credentialsecret) This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) The Credential Secret dropdown lists the secrets in all namespaces.
|
||||
1. **Bucket Name**: The name of the S3 bucket where backup files will be stored.
|
||||
1. **Region** (optional): The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. This field isn't needed for configuring MinIO.
|
||||
1. **Folder** (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., `rancher/cluster1`) are not supported.
|
||||
1. **Endpoint**: The [endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) that is used to access S3 in the region of your bucket.
|
||||
1. **Endpoint CA** (optional): This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration)
|
||||
1. **Skip TLS Verifications** (optional): Set to true if you are not using TLS.
|
||||
|
||||
|
||||
| YAML Directive Name | Description | Required |
|
||||
| ---------------- | ---------------- | ------------ |
|
||||
| `credentialSecretName` | If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives `accessKey` and `secretKey`. It can be in any namespace as long as you provide that namespace in `credentialSecretNamespace`. An example secret is [here.](#example-credentialsecret) This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) | |
|
||||
| `credentialSecretNamespace` | The namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) | |
|
||||
| `bucketName` | The name of the S3 bucket where backup files will be stored. | ✓ |
|
||||
| `folder` | The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., `rancher/cluster1`) are not supported. | |
|
||||
| `region` | The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. | ✓ |
|
||||
| `endpoint` | The [endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) that is used to access S3 in the region of your bucket. | ✓ |
|
||||
| `endpointCA` | This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration) | |
|
||||
| `insecureTLSSkipVerify` | Set to true if you are not using TLS. | |
|
||||
|
||||
### Example S3 Storage Configuration
|
||||
|
||||
```yaml
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
### Example MinIO Configuration
|
||||
|
||||
```yaml
|
||||
s3:
|
||||
credentialSecretName: minio-creds
|
||||
bucketName: rancherbackups
|
||||
endpoint: minio.35.202.130.254.xip.io
|
||||
endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t
|
||||
```
|
||||
### Example credentialSecret
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: creds
|
||||
type: Opaque
|
||||
data:
|
||||
accessKey: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
### IAM Permissions for EC2 Nodes to Access S3
|
||||
|
||||
There are two ways to set up the `rancher-backup` operator to use S3 as the backup storage location.
|
||||
|
||||
One way is to configure the `credentialSecretName` in the Backup custom resource, which refers to AWS credentials that have access to S3.
|
||||
|
||||
If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3.
|
||||
|
||||
To allow a node to access S3, follow the instructions in the [AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/) to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the `Resource` with your bucket name:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:ListBucket"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::rancher-backups"
|
||||
]
|
||||
},
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:PutObject",
|
||||
"s3:GetObject",
|
||||
"s3:DeleteObject",
|
||||
"s3:PutObjectAcl"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::rancher-backups/*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the `credentialSecretName` directive can be left empty in the Backup custom resource.
|
||||
|
||||
# Examples
|
||||
|
||||
For example Backup custom resources, refer to [this page.](../../examples/#backup)
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
title: Rancher Backup Configuration Reference
|
||||
shortTitle: Configuration
|
||||
weight: 4
|
||||
---
|
||||
|
||||
- [Backup configuration](./backup-config)
|
||||
- [Restore configuration](./restore-config)
|
||||
- [Storage location configuration](./storage-config)
|
||||
- [Example Backup and Restore Custom Resources](../examples)
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
title: Restore Configuration
|
||||
shortTitle: Restore
|
||||
weight: 2
|
||||
---
|
||||
|
||||
The Restore Create page lets you provide details of the backup to restore from
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/restore.png" "">}}
|
||||
|
||||
- [Backup Source](#backup-source)
|
||||
- [An Existing Backup Config](#an-existing-backup-config)
|
||||
- [The default storage target](#the-default-storage-target)
|
||||
- [An S3-compatible object store](#an-s3-compatible-object-store)
|
||||
- [Encryption](#encryption)
|
||||
- [Prune during restore](#prune-during-restore)
|
||||
- [Getting the Backup Filename from S3](#getting-the-backup-filename-from-s3)
|
||||
|
||||
# Backup Source
|
||||
Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details
|
||||
|
||||
|
||||
|
||||
|
||||
### An existing backup config
|
||||
|
||||
Selecting this option will populate the **Target Backup** dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the **Backup Filename** field for you, and will also pass the backup source information from the selected Backup to the operator.
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/existing.png" "">}}
|
||||
|
||||
If the Backup custom resource does not exist in the cluster, you need to get the exact filename and provide the backup source details with the default storage target or an S3-compatible object store.
|
||||
|
||||
|
||||
### The default storage target
|
||||
|
||||
Select this option if you are restoring from a backup file that exists in the default storage location configured at the operator-level. The operator-level configuration is the storage location that was configured when the `rancher-backup` operator was installed or upgraded. Provide the exact filename in the **Backup Filename** field.
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/default.png" "">}}
|
||||
|
||||
### An S3-compatible object store
|
||||
|
||||
Select this option if no default storage location is configured at the operator-level, OR if the backup file exists in a different S3 bucket than the one configured as the default storage location. Provide the exact filename in the **Backup Filename** field. Refer to [this section](#getting-the-backup-filename-from-s3) for exact steps on getting the backup filename from s3. Fill in all the details for the S3 compatible object store. Its fields are exactly same as ones for the `backup.StorageLocation` configuration in the [Backup custom resource.](../../configuration/backup-config/#storage-location)
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/s3store.png" "">}}
|
||||
|
||||
# Encryption
|
||||
|
||||
If the backup was created with encryption enabled, its file will have `.enc` suffix. Choosing such a Backup, or providing a backup filename with `.enc` suffix will display another dropdown named **Encryption Config Secret**.
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/encryption.png" "">}}
|
||||
|
||||
The Secret selected from this dropdown must have the same contents as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail
|
||||
|
||||
The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. |
|
||||
|
||||
> **Important**
|
||||
This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail.
|
||||
|
||||
# Prune During Restore
|
||||
|
||||
* **Prune**: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the **Prune** flag is enabled. Prune is enabled by default and it is recommended to keep it enabled.
|
||||
* **Delete Timeout**: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `prune` | Delete the resources managed by Rancher that are not present in the backup (Recommended). |
|
||||
| `deleteTimeoutSeconds` | Amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. |
|
||||
|
||||
# Getting the Backup Filename from S3
|
||||
|
||||
This is the name of the backup file that the `rancher-backup` operator will use to perform the restore.
|
||||
|
||||
To obtain this file name from S3, go to your S3 bucket (and folder if it was specified while performing backup).
|
||||
|
||||
Copy the filename and store it in your Restore custom resource. So assuming the name of your backup file is `backupfile`,
|
||||
|
||||
- If your bucket name is `s3bucket` and no folder was specified, then the `backupFilename` to use will be `backupfile`.
|
||||
- If your bucket name is `s3bucket` and the base folder is`s3folder`, the `backupFilename` to use is only `backupfile` .
|
||||
- If there is a subfolder inside `s3Folder` called `s3sub`, and that has your backup file, then the `backupFilename` to use is `s3sub/backupfile`.
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `backupFilename` | This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. |
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
title: Backup Storage Location Configuration
|
||||
shortTitle: Storage
|
||||
weight: 3
|
||||
---
|
||||
|
||||
Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible object store.
|
||||
|
||||
Only one storage location can be configured at the operator level.
|
||||
|
||||
- [Storage Location Configuration](#storage-location-configuration)
|
||||
- [No Default Storage Location](#no-default-storage-location)
|
||||
- [S3-compatible Object Store](#s3-compatible-object-store)
|
||||
- [Use an existing StorageClass](#existing-storageclass)
|
||||
- [Use an existing PersistentVolume](#existing-persistent-volume)
|
||||
- [Encryption](#encryption)
|
||||
- [Example values.yaml for the rancher-backup Helm Chart](#example-values-yaml-for-the-rancher-backup-helm-chart)
|
||||
|
||||
# Storage Location Configuration
|
||||
|
||||
### No Default Storage Location
|
||||
|
||||
You can choose to not have any operator-level storage location configured. If you select this option, you must configure an S3-compatible object store as the storage location for each individual backup.
|
||||
|
||||
### S3-compatible Object Store
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------- | -------------- |
|
||||
| Credential Secret | Choose the credentials for S3 from your secrets in Rancher. [Example]({{<baseurl>}}/rancher/v2.6/en/backups/examples/#example-credential-secret-for-storing-backups-in-s3). |
|
||||
| Bucket Name | Enter the name of the [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html) where the backups will be stored. Default: `rancherbackups`. |
|
||||
| Region | The [AWS region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. |
|
||||
| Folder | The [folder in the S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html) where the backups will be stored. |
|
||||
| Endpoint | The [S3 endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) For example, `s3.us-west-2.amazonaws.com`. |
|
||||
| Endpoint CA | The CA cert used to for the S3 endpoint. Default: base64 encoded CA cert |
|
||||
| insecureTLSSkipVerify | Set to true if you are not using TLS. |
|
||||
|
||||
### Existing StorageClass
|
||||
|
||||
Installing the `rancher-backup` chart by selecting the StorageClass option will create a Persistent Volume Claim (PVC), and Kubernetes will in turn dynamically provision a Persistent Volume (PV) where all the backups will be saved by default.
|
||||
|
||||
For information about creating storage classes refer to [this section.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/provisioning-new-storage/)
|
||||
|
||||
> **Important**
|
||||
It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.
|
||||
If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it.
|
||||
|
||||
### Existing Persistent Volume
|
||||
|
||||
Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to [this section.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/attaching-existing-storage/#2-add-a-persistent-volume-that-refers-to-the-persistent-storage)
|
||||
|
||||
> **Important**
|
||||
It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.
|
||||
|
||||
|
||||
# Example values.yaml for the rancher-backup Helm Chart
|
||||
|
||||
The documented `values.yaml` file that can be used to configure `rancher-backup` operator when the Helm CLI is used can be found in the [backup-restore-operator repository.](https://github.com/rancher/backup-restore-operator/blob/master/charts/rancher-backup/values.yaml)
|
||||
|
||||
For more information about `values.yaml` files and configuring Helm charts during installation, refer to the [Helm documentation.](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)
|
||||
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: Backing up Rancher Installed with Docker
|
||||
shortTitle: Backups
|
||||
weight: 3
|
||||
---
|
||||
|
||||
After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.
|
||||
|
||||
## Before You Start
|
||||
|
||||
During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
In this command, `<DATE>` is a placeholder for the date that the data container and backup were created. `9-27-18` for example.
|
||||
|
||||
Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup).
|
||||
|
||||
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code><RANCHER_CONTAINER_TAG></code> and <code><RANCHER_CONTAINER_NAME></code></sup>
|
||||
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version of Rancher that you're creating a backup for. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped with `docker ps -a`. Use these commands for help anytime while creating backups.
|
||||
|
||||
## Creating a Backup
|
||||
|
||||
This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.
|
||||
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container.
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
1. <a id="backup"></a>Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
|
||||
|
||||
```
|
||||
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
```
|
||||
|
||||
1. <a id="tarball"></a>From the data container that you just created (<code>rancher-data-<DATE></code>), create a backup tarball (<code>rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz</code>). Use the following command, replacing each placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
**Step Result:** A stream of commands runs on the screen.
|
||||
|
||||
1. Enter the `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Move your backup tarball to a safe location external to your Rancher Server. Then delete the `rancher-data-<DATE>` container from your Rancher Server.
|
||||
|
||||
1. Restart Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container:
|
||||
|
||||
```
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Docker Installs]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/docker-restores) if you need to restore backup data.
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
title: Backup and Restore for Rancher Installed with Docker
|
||||
shortTitle: Docker Installs
|
||||
weight: 10
|
||||
---
|
||||
|
||||
- [Backups](./docker-backups)
|
||||
- [Restores](./docker-restores)
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: Restoring Backups—Docker Installs
|
||||
shortTitle: Restores
|
||||
weight: 3
|
||||
---
|
||||
|
||||
If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.
|
||||
|
||||
## Before You Start
|
||||
|
||||
During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
|
||||
busybox sh -c "rm /var/lib/rancher/* -rf && \
|
||||
tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"
|
||||
```
|
||||
|
||||
In this command, `<RANCHER_CONTAINER_NAME>` and `<RANCHER_VERSION>-<DATE>` are environment variables for your Rancher deployment.
|
||||
|
||||
Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.
|
||||
|
||||
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code><RANCHER_CONTAINER_TAG></code> and <code><RANCHER_CONTAINER_NAME></code></sup>
|
||||
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version number for your Rancher backup. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.
|
||||
|
||||
## Restoring Backups
|
||||
|
||||
Using a [backup]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/docker-backups) that you created earlier, restore Rancher to its last known healthy state.
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container:
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
1. Move the backup tarball that you created during completion of [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/docker-backups) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there.
|
||||
|
||||
If you followed the naming convention we suggested in [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/docker-backups/), it will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes.
|
||||
|
||||
>**Warning!** This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
|
||||
busybox sh -c "rm /var/lib/rancher/* -rf && \
|
||||
tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"
|
||||
```
|
||||
|
||||
**Step Result:** A series of commands should run.
|
||||
|
||||
1. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data.
|
||||
|
||||
```
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
1. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored.
|
||||
@@ -1,308 +0,0 @@
|
||||
---
|
||||
title: Examples
|
||||
weight: 5
|
||||
---
|
||||
|
||||
This section contains examples of Backup and Restore custom resources.
|
||||
|
||||
The default backup storage location is configured when the `rancher-backup` operator is installed or upgraded.
|
||||
|
||||
Encrypted backups can only be restored if the Restore custom resource uses the same encryption configuration secret that was used to create the backup.
|
||||
|
||||
- [Backup](#backup)
|
||||
- [Backup in the default location with encryption](#backup-in-the-default-location-with-encryption)
|
||||
- [Recurring backup in the default location](#recurring-backup-in-the-default-location)
|
||||
- [Encrypted recurring backup in the default location](#encrypted-recurring-backup-in-the-default-location)
|
||||
- [Encrypted backup in Minio](#encrypted-backup-in-minio)
|
||||
- [Backup in S3 using AWS credential secret](#backup-in-s3-using-aws-credential-secret)
|
||||
- [Recurring backup in S3 using AWS credential secret](#recurring-backup-in-s3-using-aws-credential-secret)
|
||||
- [Backup from EC2 nodes with IAM permission to access S3](#backup-from-ec2-nodes-with-iam-permission-to-access-s3)
|
||||
- [Restore](#restore)
|
||||
- [Restore using the default backup file location](#restore-using-the-default-backup-file-location)
|
||||
- [Restore for Rancher migration](#restore-for-rancher-migration)
|
||||
- [Restore from encrypted backup](#restore-from-encrypted-backup)
|
||||
- [Restore an encrypted backup from Minio](#restore-an-encrypted-backup-from-minio)
|
||||
- [Restore from backup using an AWS credential secret to access S3](#restore-from-backup-using-an-aws-credential-secret-to-access-s3)
|
||||
- [Restore from EC2 nodes with IAM permissions to access S3](#restore-from-ec2-nodes-with-iam-permissions-to-access-s3)
|
||||
- [Example Credential Secret for Storing Backups in S3](#example-credential-secret-for-storing-backups-in-s3)
|
||||
- [Example EncryptionConfiguration](#example-encryptionconfiguration)
|
||||
|
||||
# Backup
|
||||
|
||||
This section contains example Backup custom resources.
|
||||
|
||||
### Backup in the Default Location with Encryption
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-location-encrypted-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Recurring Backup in the Default Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-location-recurring-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
### Encrypted Recurring Backup in the Default Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-enc-recurring-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 3
|
||||
```
|
||||
|
||||
### Encrypted Backup in Minio
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: minio-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: minio-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancherbackups
|
||||
endpoint: minio.xip.io
|
||||
endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Backup in S3 Using AWS Credential Secret
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Recurring Backup in S3 Using AWS Credential Secret
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-recurring-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
### Backup from EC2 Nodes with IAM Permission to Access S3
|
||||
|
||||
This example shows that the AWS credential secret does not have to be provided to create a backup if the nodes running `rancher-backup` have [these permissions for access to S3.](../configuration/backup-config/#iam-permissions-for-ec2-nodes-to-access-s3)
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-iam-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
# Restore
|
||||
|
||||
This section contains example Restore custom resources.
|
||||
|
||||
### Restore Using the Default Backup File Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-default
|
||||
spec:
|
||||
backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz
|
||||
# encryptionConfigSecretName: test-encryptionconfig
|
||||
```
|
||||
|
||||
### Restore for Rancher Migration
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-migration
|
||||
spec:
|
||||
backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
|
||||
prune: false
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
### Restore from Encrypted Backup
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-encrypted
|
||||
spec:
|
||||
backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Restore an Encrypted Backup from Minio
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-minio
|
||||
spec:
|
||||
backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: minio-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancherbackups
|
||||
endpoint: minio.xip.io
|
||||
endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t
|
||||
encryptionConfigSecretName: test-encryptionconfig
|
||||
```
|
||||
|
||||
### Restore from Backup Using an AWS Credential Secret to Access S3
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-s3-demo
|
||||
spec:
|
||||
backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
encryptionConfigSecretName: test-encryptionconfig
|
||||
```
|
||||
|
||||
### Restore from EC2 Nodes with IAM Permissions to Access S3
|
||||
|
||||
This example shows that the AWS credential secret does not have to be provided to restore from backup if the nodes running `rancher-backup` have [these permissions for access to S3.](../configuration/backup-config/#iam-permissions-for-ec2-nodes-to-access-s3)
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-s3-demo
|
||||
spec:
|
||||
backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz
|
||||
storageLocation:
|
||||
s3:
|
||||
bucketName: rajashree-backup-test
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
encryptionConfigSecretName: test-encryptionconfig
|
||||
```
|
||||
|
||||
# Example Credential Secret for Storing Backups in S3
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: creds
|
||||
type: Opaque
|
||||
data:
|
||||
accessKey: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
# Example EncryptionConfiguration
|
||||
|
||||
The snippet below demonstrates two different types of secrets and their relevance with respect to Backup and Restore of custom resources.
|
||||
|
||||
The first example is that of a secret that is used to encrypt the backup files. The backup operator, in this case, will not be able to read the secrets encryption file. It only uses the contents of the secret.
|
||||
|
||||
The second example is that of a Kubernetes secrets encryption config file that is used to encrypt secrets when stored in etcd. **When backing up the etcd datastore, be sure to also back up the EncryptionConfiguration.** Failure to do so will result in an inability to use the restored data if secrets encryption was in use at the time the data was backed up.
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: apiserver.config.k8s.io/v1
|
||||
kind: EncryptionConfiguration
|
||||
resources:
|
||||
- resources:
|
||||
- secrets
|
||||
providers:
|
||||
- aesgcm:
|
||||
keys:
|
||||
- name: key1
|
||||
secret: c2VjcmV0IGlzIHNlY3VyZQ==
|
||||
- name: key2
|
||||
secret: dGhpcyBpcyBwYXNzd29yZA==
|
||||
- aescbc:
|
||||
keys:
|
||||
- name: key1
|
||||
secret: c2VjcmV0IGlzIHNlY3VyZQ==
|
||||
- name: key2
|
||||
secret: dGhpcyBpcyBwYXNzd29yZA==
|
||||
- secretbox:
|
||||
keys:
|
||||
- name: key1
|
||||
secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
title: Migrating Rancher to a New Cluster
|
||||
weight: 3
|
||||
---
|
||||
|
||||
If you are migrating Rancher to a new Kubernetes cluster, you don't need to install Rancher on the new cluster first. If Rancher is restored to a new cluster with Rancher already installed, it can cause problems.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These instructions assume you have [created a backup](../back-up-rancher) and you have already installed a new Kubernetes cluster where Rancher will be deployed.
|
||||
|
||||
>**Warning:** It is required to use the same hostname that was set as the server URL in the first cluster. If not done, downstream clusters will show as unavailable in the cluster management page of the UI, and you won't be able to click inside the cluster or on the cluster's <b>Explore</b> button.
|
||||
|
||||
Rancher version must be v2.5.0 and up
|
||||
|
||||
Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes clusters such as Amazon EKS clusters. For help installing Kubernetes, refer to the documentation of the Kubernetes distribution. One of Rancher's Kubernetes distributions may also be used:
|
||||
|
||||
- [RKE Kubernetes installation docs]({{<baseurl>}}/rke/latest/en/installation/)
|
||||
- [K3s Kubernetes installation docs]({{<baseurl>}}/k3s/latest/en/installation/)
|
||||
|
||||
### 1. Install the rancher-backup Helm chart
|
||||
Install version 2.x.x of the rancher-backup chart. The following assumes a connected environment with access to DockerHub:
|
||||
```
|
||||
helm repo add rancher-charts https://charts.rancher.io
|
||||
helm repo update
|
||||
helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION
|
||||
helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION
|
||||
```
|
||||
</br>
|
||||
For an **air-gapped environment**, use the option below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup-crd helm chart.
|
||||
```
|
||||
--set image.repository $REGISTRY/rancher/backup-restore-operator
|
||||
```
|
||||
|
||||
### 2. Restore from backup using a Restore custom resource
|
||||
|
||||
>**Important:** Kubernetes v1.22, available as an experimental feature of v2.6.3, does not support restoring from backup files containing CRDs with the apiVersion `apiextensions.k8s.io/v1beta1`. In v1.22, the default `resourceSet` in the rancher-backup app is updated to collect only CRDs that use `apiextensions.k8s.io/v1`. There are currently two ways to work around this issue:
|
||||
>
|
||||
1. Update the default `resourceSet` to collect the CRDs with the apiVersion v1.
|
||||
1. Update the default `resourceSet` and the client to use the new APIs internally, with `apiextensions.k8s.io/v1` as the replacement.
|
||||
>
|
||||
> - Note that when making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different.
|
||||
|
||||
If you are using an S3 store as the backup source and need to use your S3 credentials for restore, create a secret in this cluster using your S3 credentials. The Secret data must have two keys - `accessKey` and `secretKey` - that contain the S3 credentials.
|
||||
|
||||
**Warning:** The values `accessKey` and `secretKey` in the example below must be base64-encoded first when creating the object directly. If not encoded first, the pasted values will cause errors when you are attempting to backup or restore.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: s3-creds
|
||||
type: Opaque
|
||||
stringData:
|
||||
accessKey: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
This secret can be created in any namespace; with the above example, it will get created in the default namespace.
|
||||
|
||||
In the Restore custom resource, `prune` must be set to false.
|
||||
|
||||
Create a Restore custom resource like the example below:
|
||||
|
||||
```yaml
|
||||
# migrationResource.yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-migration
|
||||
spec:
|
||||
backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
|
||||
prune: false
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: backup-test
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
>**Important:** The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the Secret containing the encryption config file. If you only have the encryption config file, but don't have a secret created with it in this cluster, use the following steps to create the secret:
|
||||
|
||||
1. The encryption configuration file must be named `encryption-provider-config.yaml`, and the `--from-file` flag must be used to create this secret. So save your `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command:
|
||||
```
|
||||
kubectl create secret generic encryptionconfig \
|
||||
--from-file=./encryption-provider-config.yaml \
|
||||
-n cattle-resources-system
|
||||
```
|
||||
|
||||
1. Apply the manifest, and watch for the Restore resources status:
|
||||
|
||||
Apply the resource:
|
||||
```
|
||||
kubectl apply -f migrationResource.yaml
|
||||
```
|
||||
|
||||
Watch the Restore status:
|
||||
```
|
||||
kubectl get restore
|
||||
```
|
||||
|
||||
Watch the restoration logs:
|
||||
```
|
||||
kubectl logs -n cattle-resources-system --tail 100 -f rancher-backup-xxx-xxx
|
||||
```
|
||||
|
||||
Once the Restore resource has the status `Completed`, you can continue the Rancher installation.
|
||||
|
||||
### 3. Install cert-manager
|
||||
|
||||
Follow the steps to [install cert-manager]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#5-install-cert-manager) in the documentation about installing cert-manager on Kubernetes.
|
||||
|
||||
### 4. Bring up Rancher with Helm
|
||||
|
||||
Use the same version of Helm to install Rancher, that was used on the first cluster.
|
||||
|
||||
```
|
||||
helm install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<same hostname as the server URL from the first Rancher server> \
|
||||
```
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
title: Restoring Rancher
|
||||
weight: 2
|
||||
---
|
||||
|
||||
This page outlines how to perform a restore with Rancher.
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> * Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher)
|
||||
> * While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore.
|
||||
> * If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/rollbacks/)
|
||||
|
||||
### Additional Steps for Rollbacks with Rancher v2.6.4+
|
||||
|
||||
In Rancher v2.6.4, the cluster-api module has been upgraded from v0.4.4 to v1.0.2 in which the apiVersion of CAPI CRDs are upgraded from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. This has the effect of causing rollbacks from Rancher v2.6.4 to any previous version of Rancher v2.6.x to fail because the previous version the CRDs needed to roll back are no longer available in v1beta1.
|
||||
|
||||
To avoid this, the Rancher resource cleanup scripts should be run **before** the restore or rollback is attempted. Specifically, two scripts have been created to assist you: one to clean up the cluster (`cleanup.sh`), and one to check for any Rancher-related resources in the cluster (`verify.sh`). Details on the cleanup script can be found in the [rancherlabs/support-tools repo](https://github.com/rancherlabs/support-tools/tree/master/rancher-cleanup).
|
||||
|
||||
> **Caution** Rancher will be down as the `cleanup` script runs as it deletes the resources created by rancher.
|
||||
|
||||
The additional preparations:
|
||||
|
||||
1. Follow these [instructions](https://github.com/rancherlabs/support-tools/blob/master/rancher-cleanup/README.md) to run the scripts.
|
||||
1. Follow these [instructions](https://rancher.com/docs/rancher/v2.6/en/backups/migrating-rancher/) to install the rancher-backup Helm chart on the existing cluster and restore the previous state.
|
||||
1. Omit Step 3.
|
||||
1. When Step 4 is reached, install the required Rancher v2.6.x version on the local cluster you intend to roll back to.
|
||||
|
||||
### Create the Restore Custom Resource
|
||||
|
||||
A restore is performed by creating a Restore custom resource.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the `local` cluster and click **Explore**. The `local` cluster runs the Rancher server.
|
||||
1. In the left navigation bar, click **Rancher Backups > Restores**.
|
||||
1. Click **Create**.
|
||||
1. Create the Restore with the form, or with YAML. For creating the Restore resource using form, refer to the [configuration reference]({{<baseurl>}}/rancher/v2.6/en/backups/configuration/restore-config) and to the [examples.]({{<baseurl>}}/rancher/v2.6/en/backups/examples)
|
||||
1. For using the YAML editor, we can click **Create > Create from YAML**. Enter the Restore YAML.
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-migration
|
||||
spec:
|
||||
backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
For help configuring the Restore, refer to the [configuration reference]({{<baseurl>}}/rancher/v2.6/en/backups/configuration/restore-config) and to the [examples.]({{<baseurl>}}/rancher/v2.6/en/backups/examples)
|
||||
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The rancher-operator scales down the rancher deployment during restore, and scales it back up once the restore completes. The resources are restored in this order:
|
||||
|
||||
1. Custom Resource Definitions (CRDs)
|
||||
2. Cluster-scoped resources
|
||||
3. Namespaced resources
|
||||
|
||||
### Logs
|
||||
|
||||
To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:
|
||||
|
||||
```
|
||||
kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores.
|
||||
|
||||
### Known Issues
|
||||
In some cases, after restoring the backup, Rancher logs will show errors similar to the following:
|
||||
```
|
||||
2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing
|
||||
```
|
||||
This happens because one of the resources that was just restored has finalizers, but the related resources have been deleted so the handler cannot find it.
|
||||
|
||||
To eliminate the errors, we need to find and delete the resource that causes the error. See more information [here](https://github.com/rancher/rancher/issues/35050#issuecomment-937968556)
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: Best Practices Guide
|
||||
weight: 4
|
||||
---
|
||||
|
||||
The purpose of this section is to consolidate best practices for Rancher implementations. This also includes recommendations for related technologies, such as Kubernetes, Docker, containers, and more. The objective is to improve the outcome of a Rancher implementation using the operational experience of Rancher and its customers.
|
||||
|
||||
If you have any questions about how these might apply to your use case, please contact your Customer Success Manager or Support.
|
||||
|
||||
Use the navigation bar on the left to find the current best practices for managing and deploying the Rancher Server.
|
||||
|
||||
For more guidance on best practices, you can consult these resources:
|
||||
|
||||
- [Security]({{<baseurl>}}/rancher/v2.6/en/security/)
|
||||
- [Rancher Blog](https://www.suse.com/c/rancherblog/)
|
||||
- [Rancher Forum](https://forums.rancher.com/)
|
||||
- [Rancher Users Slack](https://slack.rancher.io/)
|
||||
- [Rancher Labs YouTube Channel - Online Meetups, Demos, Training, and Webinars](https://www.youtube.com/channel/UCh5Xtp82q8wjijP8npkVTBA/featured)
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Tips for Setting Up Containers
|
||||
weight: 100
|
||||
---
|
||||
|
||||
Running well-built containers can greatly impact the overall performance and security of your environment.
|
||||
|
||||
Below are a few tips for setting up your containers.
|
||||
|
||||
For a more detailed discussion of security for containers, you can also refer to Rancher's [Guide to Container Security.](https://rancher.com/complete-guide-container-security)
|
||||
|
||||
### Use a Common Container OS
|
||||
|
||||
When possible, you should try to standardize on a common container base OS.
|
||||
|
||||
Smaller distributions such as Alpine and BusyBox reduce container image size and generally have a smaller attack/vulnerability surface.
|
||||
|
||||
Popular distributions such as Ubuntu, Fedora, and CentOS are more field-tested and offer more functionality.
|
||||
|
||||
### Start with a FROM scratch container
|
||||
If your microservice is a standalone static binary, you should use a FROM scratch container.
|
||||
|
||||
The FROM scratch container is an [official Docker image](https://hub.docker.com/_/scratch) that is empty so that you can use it to design minimal images.
|
||||
|
||||
This will have the smallest attack surface and smallest image size.
|
||||
|
||||
### Run Container Processes as Unprivileged
|
||||
When possible, use a non-privileged user when running processes within your container. While container runtimes provide isolation, vulnerabilities and attacks are still possible. Inadvertent or accidental host mounts can also be impacted if the container is running as root. For details on configuring a security context for a pod or container, refer to the [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
|
||||
|
||||
### Define Resource Limits
|
||||
Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices.
|
||||
|
||||
In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs.
|
||||
|
||||
When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.
|
||||
|
||||
The Kubernetes docs have more information on how resource limits can be set at the [container level](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) and the namespace level.
|
||||
|
||||
### Define Resource Requirements
|
||||
You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining `resources.requests` in the resource requests field in a pod's container spec. For details, refer to the [Kubernetes docs](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container).
|
||||
|
||||
> **Note:** If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace.
|
||||
|
||||
It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load.
|
||||
|
||||
### Liveness and Readiness Probes
|
||||
Set up liveness and readiness probes for your container. Unless your container completely crashes, Kubernetes will not know it's unhealthy unless you create an endpoint or mechanism that can report container status. Alternatively, make sure your container halts and crashes if unhealthy.
|
||||
|
||||
The Kubernetes docs show how to [configure liveness and readiness probes for containers.](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
title: Logging Best Practices
|
||||
weight: 1
|
||||
---
|
||||
In this guide, we recommend best practices for cluster-level logging and application logging.
|
||||
|
||||
- [Cluster-level Logging](#cluster-level-logging)
|
||||
- [Application Logging](#application-logging)
|
||||
- [General Best Practices](#general-best-practices)
|
||||
|
||||
Before Rancher v2.5, logging in Rancher has historically been a pretty static integration. There were a fixed list of aggregators to choose from (ElasticSearch, Splunk, Kafka, Fluentd and Syslog), and only two configuration points to choose (Cluster-level and Project-level).
|
||||
|
||||
Rancher provides a flexible experience for log aggregation. With the logging feature, administrators and users alike can deploy logging that meets fine-grained collection criteria while offering a wider array of destinations and configuration options.
|
||||
|
||||
"Under the hood", Rancher logging uses the Banzai Cloud logging operator. We provide manageability of this operator (and its resources), and tie that experience in with managing your Rancher clusters.
|
||||
|
||||
# Cluster-level Logging
|
||||
|
||||
### Cluster-wide Scraping
|
||||
|
||||
For some users, it is desirable to scrape logs from every container running in the cluster. This usually coincides with your security team's request (or requirement) to collect all logs from all points of execution.
|
||||
|
||||
In this scenario, it is recommended to create at least two _ClusterOutput_ objects - one for your security team (if you have that requirement), and one for yourselves, the cluster administrators. When creating these objects take care to choose an output endpoint that can handle the significant log traffic coming from the entire cluster. Also make sure to choose an appropriate index to receive all these logs.
|
||||
|
||||
Once you have created these _ClusterOutput_ objects, create a _ClusterFlow_ to collect all the logs. Do not define any _Include_ or _Exclude_ rules on this flow. This will ensure that all logs from across the cluster are collected. If you have two _ClusterOutputs_, make sure to send logs to both of them.
|
||||
|
||||
### Kubernetes Components
|
||||
|
||||
_ClusterFlows_ have the ability to collect logs from all containers on all hosts in the Kubernetes cluster. This works well in cases where those containers are part of a Kubernetes pod; however, RKE containers exist outside of the scope of Kubernetes.
|
||||
|
||||
Currently the logs from RKE containers are collected, but are not able to easily be filtered. This is because those logs do not contain information as to the source container (e.g. `etcd` or `kube-apiserver`).
|
||||
|
||||
A future release of Rancher will include the source container name which will enable filtering of these component logs. Once that change is made, you will be able to customize a _ClusterFlow_ to retrieve **only** the Kubernetes component logs, and direct them to an appropriate output.
|
||||
|
||||
# Application Logging
|
||||
|
||||
Best practice not only in Kubernetes but in all container-based applications is to direct application logs to `stdout`/`stderr`. The container runtime will then trap these logs and do **something** with them - typically writing them to a file. Depending on the container runtime (and its configuration), these logs can end up in any number of locations.
|
||||
|
||||
In the case of writing the logs to a file, Kubernetes helps by creating a `/var/log/containers` directory on each host. This directory symlinks the log files to their actual destination (which can differ based on configuration or container runtime).
|
||||
|
||||
Rancher logging will read all log entries in `/var/log/containers`, ensuring that all log entries from all containers (assuming a default configuration) will have the opportunity to be collected and processed.
|
||||
|
||||
### Specific Log Files
|
||||
|
||||
Log collection only retrieves `stdout`/`stderr` logs from pods in Kubernetes. But what if we want to collect logs from other files that are generated by applications? Here, a log streaming sidecar (or two) may come in handy.
|
||||
|
||||
The goal of setting up a streaming sidecar is to take log files that are written to disk, and have their contents streamed to `stdout`. This way, the Banzai Logging Operator can pick up those logs and send them to your desired output.
|
||||
|
||||
To set this up, edit your workload resource (e.g. Deployment) and add the following sidecar definition:
|
||||
|
||||
```
|
||||
...
|
||||
containers:
|
||||
- args:
|
||||
- -F
|
||||
- /path/to/your/log/file.log
|
||||
command:
|
||||
- tail
|
||||
image: busybox
|
||||
name: stream-log-file-[name]
|
||||
volumeMounts:
|
||||
- mountPath: /path/to/your/log
|
||||
name: mounted-log
|
||||
...
|
||||
```
|
||||
|
||||
This will add a container to your workload definition that will now stream the contents of (in this example) `/path/to/your/log/file.log` to `stdout`.
|
||||
|
||||
This log stream is then automatically collected according to any _Flows_ or _ClusterFlows_ you have setup. You may also wish to consider creating a _Flow_ specifically for this log file by targeting the name of the container. See example:
|
||||
|
||||
```
|
||||
...
|
||||
spec:
|
||||
match:
|
||||
- select:
|
||||
container_names:
|
||||
- stream-log-file-name
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
# General Best Practices
|
||||
|
||||
- Where possible, output structured log entries (e.g. `syslog`, JSON). This makes handling of the log entry easier as there are already parsers written for these formats.
|
||||
- Try to provide the name of the application that is creating the log entry, in the entry itself. This can make troubleshooting easier as Kubernetes objects do not always carry the name of the application as the object name. For instance, a pod ID may be something like `myapp-098kjhsdf098sdf98` which does not provide much information about the application running inside the container.
|
||||
- Except in the case of collecting all logs cluster-wide, try to scope your _Flow_ and _ClusterFlow_ objects tightly. This makes it easier to troubleshoot when problems arise, and also helps ensure unrelated log entries do not show up in your aggregator. An example of tight scoping would be to constrain a _Flow_ to a single _Deployment_ in a namespace, or perhaps even a single container within a _Pod_.
|
||||
- Keep the log verbosity down except when troubleshooting. High log verbosity poses a number of issues, chief among them being **noise**: significant events can be drowned out in a sea of `DEBUG` messages. This is somewhat mitigated with automated alerting and scripting, but highly verbose logging still places an inordinate amount of stress on the logging infrastructure.
|
||||
- Where possible, try to provide a transaction or request ID with the log entry. This can make tracing application activity across multiple log sources easier, especially when dealing with distributed applications.
|
||||
-59
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Best Practices for Rancher Managed vSphere Clusters
|
||||
shortTitle: Rancher Managed Clusters in vSphere
|
||||
---
|
||||
|
||||
This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
|
||||
|
||||
- [1. VM Considerations](#1-vm-considerations)
|
||||
- [2. Network Considerations](#2-network-considerations)
|
||||
- [3. Storage Considerations](#3-storage-considerations)
|
||||
- [4. Backups and Disaster Recovery](#4-backups-and-disaster-recovery)
|
||||
|
||||
<figcaption>Solution Overview</figcaption>
|
||||
|
||||
|
||||
|
||||
# 1. VM Considerations
|
||||
|
||||
### Leverage VM Templates to Construct the Environment
|
||||
|
||||
To facilitate consistency across the deployed Virtual Machines across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customisation options.
|
||||
|
||||
### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across ESXi Hosts
|
||||
|
||||
Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.
|
||||
|
||||
### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across Datastores
|
||||
|
||||
Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.
|
||||
|
||||
### Configure VM's as Appropriate for Kubernetes
|
||||
|
||||
It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.
|
||||
|
||||
# 2. Network Considerations
|
||||
|
||||
### Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes
|
||||
|
||||
Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.
|
||||
|
||||
### Consistent IP Addressing for VM's
|
||||
|
||||
Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
|
||||
|
||||
# 3. Storage Considerations
|
||||
|
||||
### Leverage SSD Drives for ETCD Nodes
|
||||
|
||||
ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.
|
||||
|
||||
# 4. Backups and Disaster Recovery
|
||||
|
||||
### Perform Regular Downstream Cluster Backups
|
||||
|
||||
Kubernetes uses etcd to store all its data - from configuration, state and metadata. Backing this up is crucial in the event of disaster recovery.
|
||||
|
||||
### Back up Downstream Node VMs
|
||||
|
||||
Incorporate the Rancher downstream node VM's within a standard VM backup policy.
|
||||
@@ -1,120 +0,0 @@
|
||||
---
|
||||
title: Monitoring Best Practices
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. This is not different when using Kubernetes and Rancher. Fortunately the integrated monitoring and alerting functionality makes this whole process a lot easier.
|
||||
|
||||
The [Rancher monitoring documentation]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/) describes how you can set up a complete Prometheus and Grafana stack. Out of the box this will scrape monitoring data from all system and Kubernetes components in your cluster and provide sensible dashboards and alerts for them to get started. But for a reliable setup, you also need to monitor your own workloads and adapt Prometheus and Grafana to your own specific use cases and cluster sizes. This document aims to give you best practices for this.
|
||||
|
||||
- [What to Monitor](#what-to-monitor)
|
||||
- [Configuring Prometheus Resource Usage](#configuring-prometheus-resource-usage)
|
||||
- [Scraping Custom Workloads](#scraping-custom-workloads)
|
||||
- [Monitoring in a (Micro)Service Architecture](#monitoring-in-a-micro-service-architecture)
|
||||
- [Real User Monitoring](#real-user-monitoring)
|
||||
- [Security Monitoring](#security-monitoring)
|
||||
- [Setting up Alerts](#setting-up-alerts)
|
||||
|
||||
# What to Monitor
|
||||
|
||||
Kubernetes itself, as well as applications running inside of it, form a distributed system where different components interact with each other. For the whole system and each individual component, you have to ensure performance, availability, reliability and scalability. A good resource with more details and information is Google's free [Site Reliability Engineering Book](https://landing.google.com/sre/sre-book/), especially the chapter about [Monitoring distributed systems](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/).
|
||||
|
||||
# Configuring Prometheus Resource Usage
|
||||
|
||||
When installing the integrated monitoring stack, Rancher allows to configure several settings that are dependent on the size of your cluster and the workloads running in it. This chapter covers these in more detail.
|
||||
|
||||
### Storage and Data Retention
|
||||
|
||||
The amount of storage needed for Prometheus directly correlates to the amount of time series and labels that you store and the data retention you have configured. It is important to note that Prometheus is not meant to be used as a long-term metrics storage. Data retention time is usually only a couple of days and not weeks or months. The reason for this is that Prometheus does not perform any aggregation on its stored metrics. This is great because aggregation can dilute data, but it also means that the needed storage grows linearly over time without retention.
|
||||
|
||||
One way to calculate the necessary storage is to look at the average size of a storage chunk in Prometheus with this query
|
||||
|
||||
```
|
||||
rate(prometheus_tsdb_compaction_chunk_size_bytes_sum[1h]) / rate(prometheus_tsdb_compaction_chunk_samples_sum[1h])
|
||||
```
|
||||
|
||||
Next, find out your data ingestion rate per second:
|
||||
|
||||
```
|
||||
rate(prometheus_tsdb_head_samples_appended_total[1h])
|
||||
```
|
||||
|
||||
and then multiply this with the retention time, adding a few percentage points as buffer:
|
||||
|
||||
```
|
||||
average chunk size in bytes * ingestion rate per second * retention time in seconds * 1.1 = necessary storage in bytes
|
||||
```
|
||||
|
||||
You can find more information about how to calculate the necessary storage in this [blog post](https://www.robustperception.io/how-much-disk-space-do-prometheus-blocks-use).
|
||||
|
||||
You can read more about the Prometheus storage concept in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/storage).
|
||||
|
||||
### CPU and Memory Requests and Limits
|
||||
|
||||
In larger Kubernetes clusters Prometheus can consume quite a bit of memory. The amount of memory Prometheus needs directly correlates to the amount of time series and amount of labels it stores and the scrape interval in which these are filled.
|
||||
|
||||
You can find more information about how to calculate the necessary memory in this [blog post](https://www.robustperception.io/how-much-ram-does-prometheus-2-x-need-for-cardinality-and-ingestion).
|
||||
|
||||
The amount of necessary CPUs correlate with the amount of queries you are performing.
|
||||
|
||||
### Federation and Long-term Storage
|
||||
|
||||
Prometheus is not meant to store metrics for a long amount of time, but should only be used for short term storage.
|
||||
|
||||
In order to store some, or all metrics for a long time, you can leverage Prometheus' [remote read/write](https://prometheus.io/docs/prometheus/latest/storage/#remote-storage-integrations) capabilities to connect it to storage systems like [Thanos](https://thanos.io/), [InfluxDB](https://www.influxdata.com/), [M3DB](https://www.m3db.io/), or others. You can find an example setup in this [blog post](https://rancher.com/blog/2020/prometheus-metric-federation).
|
||||
|
||||
# Scraping Custom Workloads
|
||||
|
||||
While the integrated Rancher Monitoring already scrapes system metrics from a cluster's nodes and system components, the custom workloads that you deploy on Kubernetes should also be scraped for data. For that you can configure Prometheus to do an HTTP request to an endpoint of your applications in a certain interval. These endpoints should then return their metrics in a Prometheus format.
|
||||
|
||||
In general, you want to scrape data from all the workloads running in your cluster so that you can use them for alerts or debugging issues. Often, you recognize that you need some data only when you actually need the metrics during an incident. It is good, if it is already scraped and stored. Since Prometheus is only meant to be a short-term metrics storage, scraping and keeping lots of data is usually not that expensive. If you are using a long-term storage solution with Prometheus, you can then still decide which data you are actually persisting and keeping there.
|
||||
|
||||
### About Prometheus Exporters
|
||||
|
||||
A lot of 3rd party workloads like databases, queues or web-servers either already support exposing metrics in a Prometheus format, or there are so called exporters available that translate between the tool's metrics and the format that Prometheus understands. Usually you can add these exporters as additional sidecar containers to the workload's Pods. A lot of helm charts already include options to deploy the correct exporter. Additionally you can find a curated list of exports by SysDig on [promcat.io](https://promcat.io/) and on [ExporterHub](https://exporterhub.io/).
|
||||
|
||||
### Prometheus support in Programming Languages and Frameworks
|
||||
|
||||
To get your own custom application metrics into Prometheus, you have to collect and expose these metrics directly from your application's code. Fortunately, there are already libraries and integrations available to help with this for most popular programming languages and frameworks. One example for this is the Prometheus support in the [Spring Framework](https://docs.spring.io/spring-metrics/docs/current/public/prometheus).
|
||||
|
||||
### ServiceMonitors and PodMonitors
|
||||
|
||||
Once all your workloads expose metrics in a Prometheus format, you have to configure Prometheus to scrape it. Under the hood Rancher is using the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator). This makes it easy to add additional scraping targets with ServiceMonitors and PodMonitors. A lot of helm charts already include an option to create these monitors directly. You can also find more information in the Rancher documentation.
|
||||
|
||||
### Prometheus Push Gateway
|
||||
|
||||
There are some workloads that are traditionally hard to scrape by Prometheus. Examples for these are short lived workloads like Jobs and CronJobs, or applications that do not allow sharing data between individual handled incoming requests, like PHP applications.
|
||||
|
||||
To still get metrics for these use cases, you can set up [prometheus-pushgateways](https://github.com/prometheus/pushgateway). The CronJob or PHP application would push metric updates to the pushgateway. The pushgateway aggregates and exposes them through an HTTP endpoint, which then can be scraped by Prometheus.
|
||||
|
||||
### Prometheus Blackbox Monitor
|
||||
|
||||
Sometimes it is useful to monitor workloads from the outside. For this, you can use the [Prometheus blackbox-exporter](https://github.com/prometheus/blackbox_exporter) which allows probing any kind of endpoint over HTTP, HTTPS, DNS, TCP and ICMP.
|
||||
|
||||
# Monitoring in a (Micro)Service Architecture
|
||||
|
||||
If you have a (micro)service architecture where multiple individual workloads within your cluster are communicating with each other, it is really important to have detailed metrics and traces about this traffic to understand how all these workloads are communicating with each other and where a problem or bottleneck may be.
|
||||
|
||||
Of course you can monitor all this internal traffic in all your workloads and expose these metrics to Prometheus. But this can quickly become quite work intensive. Service Meshes like Istio, which can be installed with [a click](https://rancher.com/docs/rancher/v2.6/en/istio/) in Rancher, can do this automatically and provide rich telemetry about the traffic between all services.
|
||||
|
||||
# Real User Monitoring
|
||||
|
||||
Monitoring the availability and performance of all your internal workloads is vitally important to run stable, reliable and fast applications. But these metrics only show you parts of the picture. To get a complete view it is also necessary to know how your end users are actually perceiving it. For this you can look into various [Real user monitoring solutions](https://en.wikipedia.org/wiki/Real_user_monitoring).
|
||||
|
||||
# Security Monitoring
|
||||
|
||||
In addition to monitoring workloads to detect performance, availability or scalability problems, the cluster and the workloads running into it should also be monitored for potential security problems. A good starting point is to frequently run and alert on [CIS Scans]({{<baseurl>}}/rancher/v2.6/en/cis-scans/) which check if the cluster is configured according to security best practices.
|
||||
|
||||
For the workloads, you can have a look at Kubernetes and Container security solutions like [Falco](https://falco.org/), [Aqua Kubernetes Security](https://www.aquasec.com/solutions/kubernetes-container-security/), [SysDig](https://sysdig.com/).
|
||||
|
||||
# Setting up Alerts
|
||||
|
||||
Getting all the metrics into a monitoring systems and visualizing them in dashboards is great, but you also want to be pro-actively alerted if something goes wrong.
|
||||
|
||||
The integrated Rancher monitoring already configures a sensible set of alerts that make sense in any Kubernetes cluster. You should extend these to cover your specific workloads and use cases.
|
||||
|
||||
When setting up alerts, configure them for all the workloads that are critical to the availability of your applications. But also make sure that they are not too noisy. Ideally every alert you are receiving should be because of a problem that needs your attention and needs to be fixed. If you have alerts that are firing all the time but are not that critical, there is a danger that you start ignoring your alerts all together and then miss the real important ones. Less may be more here. Start to focus on the real important metrics first, for example alert if your application is offline. Fix all the problems that start to pop up and then start to create more detailed alerts.
|
||||
|
||||
If an alert starts firing, but there is nothing you can do about it at the moment, it's also fine to silence the alert for a certain amount of time, so that you can look at it later.
|
||||
|
||||
You can find more information on how to set up alerts and notification channels in the [Rancher Documentation]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting).
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Best Practices for Rancher Managed Clusters
|
||||
shortTitle: Rancher Managed Clusters
|
||||
weight: 2
|
||||
---
|
||||
|
||||
### Logging
|
||||
|
||||
Refer to [this guide](./logging) for our recommendations for cluster-level logging and application logging.
|
||||
|
||||
### Monitoring
|
||||
|
||||
Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. Refer to this [guide](./monitoring) for our recommendations.
|
||||
|
||||
### Tips for Setting Up Containers
|
||||
|
||||
Running well-built containers can greatly impact the overall performance and security of your environment. Refer to this [guide](./containers) for tips.
|
||||
|
||||
### Best Practices for Rancher Managed vSphere Clusters
|
||||
|
||||
This [guide](./managed-vsphere) outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
|
||||
-45
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: Rancher Deployment Strategy
|
||||
weight: 100
|
||||
---
|
||||
|
||||
There are two recommended deployment strategies for a Rancher server that manages downstream Kubernetes clusters. Each one has its own pros and cons. Read more about which one would fit best for your use case:
|
||||
|
||||
* [Hub and Spoke](#hub-and-spoke-strategy)
|
||||
* [Regional](#regional-strategy)
|
||||
|
||||
# Hub & Spoke Strategy
|
||||
---
|
||||
|
||||
In this deployment scenario, there is a single Rancher control plane managing Kubernetes clusters across the globe. The control plane would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies.
|
||||
|
||||
{{< img "/img/rancher/bpg/hub-and-spoke.png" "Hub and Spoke Deployment">}}
|
||||
|
||||
### Pros
|
||||
|
||||
* Environments could have nodes and network connectivity across regions.
|
||||
* Single control plane interface to view/see all regions and environments.
|
||||
* Kubernetes does not require Rancher to operate and can tolerate losing connectivity to the Rancher control plane.
|
||||
|
||||
### Cons
|
||||
|
||||
* Subject to network latencies.
|
||||
* If the control plane goes out, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually.
|
||||
|
||||
# Regional Strategy
|
||||
---
|
||||
In the regional deployment model a control plane is deployed in close proximity to the compute nodes.
|
||||
|
||||
{{< img "/img/rancher/bpg/regional.png" "Regional Deployment">}}
|
||||
|
||||
### Pros
|
||||
|
||||
* Rancher functionality in regions stay operational if a control plane in another region goes down.
|
||||
* Network latency is greatly reduced, improving the performance of functionality in Rancher.
|
||||
* Upgrades of the Rancher control plane can be done independently per region.
|
||||
|
||||
### Cons
|
||||
|
||||
* Overhead of managing multiple Rancher installations.
|
||||
* Visibility across global Kubernetes clusters requires multiple interfaces/panes of glass.
|
||||
* Deploying multi-cluster apps in Rancher requires repeating the process for each Rancher server.
|
||||
-37
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: Tips for Running Rancher
|
||||
weight: 100
|
||||
---
|
||||
|
||||
This guide is geared toward use cases where Rancher is used to manage downstream Kubernetes clusters. The high-availability setup is intended to prevent losing access to downstream clusters if the Rancher server is not available.
|
||||
|
||||
A high-availability Kubernetes installation, defined as an installation of Rancher on a Kubernetes cluster with at least three nodes, should be used in any production installation of Rancher, as well as any installation deemed "important." Multiple Rancher instances running on multiple nodes ensure high availability that cannot be accomplished with a single node environment.
|
||||
|
||||
If you are installing Rancher in a vSphere environment, refer to the best practices documented [here.](../rancher-in-vsphere)
|
||||
|
||||
When you set up your high-availability Rancher installation, consider the following:
|
||||
|
||||
### Run Rancher on a Separate Cluster
|
||||
Don't run other workloads or microservices in the Kubernetes cluster that Rancher is installed on.
|
||||
|
||||
### Make sure nodes are configured correctly for Kubernetes ###
|
||||
It's important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node, checking that all correct ports are opened, and deploying with ssd backed etcd. More details can be found in the [kubernetes docs](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) and [etcd's performance op guide](https://etcd.io/docs/v3.4/op-guide/performance/).
|
||||
|
||||
### When using RKE: Back up the Statefile
|
||||
RKE keeps record of the cluster state in a file called `cluster.rkestate`. This file is important for the recovery of a cluster and/or the continued maintenance of the cluster through RKE. Because this file contains certificate material, we strongly recommend encrypting this file before backing up. After each run of `rke up` you should backup the state file.
|
||||
|
||||
### Run All Nodes in the Cluster in the Same Datacenter
|
||||
For best performance, run all three of your nodes in the same geographic datacenter. If you are running nodes in the cloud, such as AWS, run each node in a separate Availability Zone. For example, launch node 1 in us-west-2a, node 2 in us-west-2b, and node 3 in us-west-2c.
|
||||
|
||||
### Development and Production Environments Should be Similar
|
||||
It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration.
|
||||
|
||||
### Monitor Your Clusters to Plan Capacity
|
||||
The Rancher server's Kubernetes cluster should run within the [system and hardware requirements]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/) as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.
|
||||
|
||||
However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types.
|
||||
|
||||
Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus.
|
||||
|
||||
After you [enable monitoring]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting) in the cluster, you can set up alerts to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.
|
||||
|
||||
-91
@@ -1,91 +0,0 @@
|
||||
---
|
||||
title: Installing Rancher in a vSphere Environment
|
||||
shortTitle: On-Premises Rancher in vSphere
|
||||
weight: 3
|
||||
---
|
||||
|
||||
This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
|
||||
|
||||
- [1. Load Balancer Considerations](#1-load-balancer-considerations)
|
||||
- [2. VM Considerations](#2-vm-considerations)
|
||||
- [3. Network Considerations](#3-network-considerations)
|
||||
- [4. Storage Considerations](#4-storage-considerations)
|
||||
- [5. Backups and Disaster Recovery](#5-backups-and-disaster-recovery)
|
||||
|
||||
<figcaption>Solution Overview</figcaption>
|
||||
|
||||
|
||||
|
||||
# 1. Load Balancer Considerations
|
||||
|
||||
A load balancer is required to direct traffic to the Rancher workloads residing on the RKE nodes.
|
||||
|
||||
### Leverage Fault Tolerance and High Availability
|
||||
|
||||
Leverage the use of an external (hardware or software) load balancer that has inherit high-availability functionality (F5, NSX-T, Keepalived, etc).
|
||||
|
||||
### Back Up Load Balancer Configuration
|
||||
|
||||
In the event of a Disaster Recovery activity, availability of the Load balancer configuration will expedite the recovery process.
|
||||
|
||||
### Configure Health Checks
|
||||
|
||||
Configure the Load balancer to automatically mark nodes as unavailable if a health check is failed. For example, NGINX can facilitate this with:
|
||||
|
||||
`max_fails=3 fail_timeout=5s`
|
||||
|
||||
### Leverage an External Load Balancer
|
||||
|
||||
Avoid implementing a software load balancer within the management cluster.
|
||||
|
||||
### Secure Access to Rancher
|
||||
|
||||
Configure appropriate Firewall / ACL rules to only expose access to Rancher
|
||||
|
||||
# 2. VM Considerations
|
||||
|
||||
### Size the VM's According to Rancher Documentation
|
||||
|
||||
https://rancher.com/docs/rancher/v2.6/en/installation/requirements/
|
||||
|
||||
### Leverage VM Templates to Construct the Environment
|
||||
|
||||
To facilitate the consistency of Virtual Machines deployed across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customization options.
|
||||
|
||||
### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across ESXi Hosts
|
||||
|
||||
Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.
|
||||
|
||||
### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across Datastores
|
||||
|
||||
Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.
|
||||
|
||||
### Configure VM's as Appropriate for Kubernetes
|
||||
|
||||
It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.
|
||||
|
||||
# 3. Network Considerations
|
||||
|
||||
### Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes
|
||||
|
||||
Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.
|
||||
|
||||
### Consistent IP Addressing for VM's
|
||||
|
||||
Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
|
||||
|
||||
# 4. Storage Considerations
|
||||
|
||||
### Leverage SSD Drives for ETCD Nodes
|
||||
|
||||
ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.
|
||||
|
||||
# 5. Backups and Disaster Recovery
|
||||
|
||||
### Perform Regular Management Cluster Backups
|
||||
|
||||
Rancher stores its data in the ETCD datastore of the Kubernetes cluster it resides on. Like with any Kubernetes cluster, perform frequent, tested backups of this cluster.
|
||||
|
||||
### Back up Rancher Cluster Node VMs
|
||||
|
||||
Incorporate the Rancher management node VM's within a standard VM backup policy.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
title: Best Practices for the Rancher Server
|
||||
shortTitle: Rancher Server
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This guide contains our recommendations for running the Rancher server, and is intended to be used in situations in which Rancher manages downstream Kubernetes clusters.
|
||||
|
||||
### Recommended Architecture and Infrastructure
|
||||
|
||||
Refer to this [guide](./deployment-types) for our general advice for setting up the Rancher server on a high-availability Kubernetes cluster.
|
||||
|
||||
### Deployment Strategies
|
||||
|
||||
This [guide](./deployment-strategies) is designed to help you choose whether a regional deployment strategy or a hub-and-spoke deployment strategy is better for a Rancher server that manages downstream Kubernetes clusters.
|
||||
|
||||
### Installing Rancher in a vSphere Environment
|
||||
|
||||
This [guide](./rancher-in-vsphere) outlines a reference architecture for installing Rancher in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.
|
||||
@@ -1,292 +0,0 @@
|
||||
---
|
||||
title: CIS Scans
|
||||
weight: 17
|
||||
---
|
||||
|
||||
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark. The CIS scans can run on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE.
|
||||
|
||||
The `rancher-cis-benchmark` app leverages <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench,</a> an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes <a href="https://github.com/vmware-tanzu/sonobuoy" target="_blank">Sonobuoy</a> for report aggregation.
|
||||
|
||||
- [About the CIS Benchmark](#about-the-cis-benchmark)
|
||||
- [About the Generated Report](#about-the-generated-report)
|
||||
- [Test Profiles](#test-profiles)
|
||||
- [About Skipped and Not Applicable Tests](#about-skipped-and-not-applicable-tests)
|
||||
- [Roles-based Access Control](./rbac)
|
||||
- [Configuration](./configuration)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
- [Installing CIS Benchmark](#installing-cis-benchmark)
|
||||
- [Uninstalling CIS Benchmark](#uninstalling-cis-benchmark)
|
||||
- [Running a Scan](#running-a-scan)
|
||||
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
|
||||
- [Skipping Tests](#skipping-tests)
|
||||
- [Viewing Reports](#viewing-reports)
|
||||
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
|
||||
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
|
||||
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
|
||||
|
||||
|
||||
# About the CIS Benchmark
|
||||
|
||||
The Center for Internet Security is a 501(c\)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.
|
||||
|
||||
CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.
|
||||
|
||||
The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is
|
||||
<a href="https://learn.cisecurity.org/benchmarks" target="_blank">here.</a>
|
||||
|
||||
# About the Generated Report
|
||||
|
||||
Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.
|
||||
|
||||
By default, the CIS Benchmark v1.6 is used.
|
||||
|
||||
The Benchmark version is included in the generated report.
|
||||
|
||||
The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.
|
||||
|
||||
Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's <a href="{{<baseurl>}}/rancher/v2.6/en/security/#the-cis-benchmark-and-self-assessment" target="_blank">self-assessment guide for the corresponding Kubernetes version.</a>
|
||||
|
||||
The report contains the following information:
|
||||
|
||||
| Column in Report | Description |
|
||||
|------------------|-------------|
|
||||
| `id` | The ID number of the CIS Benchmark. |
|
||||
| `description` | The description of the CIS Benchmark test. |
|
||||
| `remediation` | What needs to be fixed in order to pass the test. |
|
||||
| `state` | Indicates if the test passed, failed, was skipped, or was not applicable. |
|
||||
| `node_type` | The node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes. |
|
||||
| `audit` | This is the audit check that `kube-bench` runs for this test. |
|
||||
| `audit_config` | Any configuration applicable to the audit script. |
|
||||
| `test_info` | Test-related info as reported by `kube-bench`, if any. |
|
||||
| `commands` | Test-related commands as reported by `kube-bench`, if any. |
|
||||
| `config_commands` | Test-related configuration data as reported by `kube-bench`, if any. |
|
||||
| `actual_value` | The test's actual value, present if reported by `kube-bench`. |
|
||||
| `expected_result` | The test's expected result, present if reported by `kube-bench`. |
|
||||
|
||||
Refer to <a href="{{<baseurl>}}/rancher/v2.6/en/security/" target="_blank">the table in the cluster hardening guide</a> for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.
|
||||
|
||||
# Test Profiles
|
||||
|
||||
The following profiles are available:
|
||||
|
||||
- Generic CIS 1.5
|
||||
- Generic CIS 1.6
|
||||
- RKE permissive 1.5
|
||||
- RKE hardened 1.5
|
||||
- RKE permissive 1.6
|
||||
- RKE hardened 1.6
|
||||
- RKE2 permissive 1.5
|
||||
- RKE2 hardened 1.5
|
||||
- RKE2 permissive 1.6
|
||||
- RKE2 hardened 1.6
|
||||
- AKS
|
||||
- EKS
|
||||
- GKE
|
||||
|
||||
You also have the ability to customize a profile by saving a set of tests to skip.
|
||||
|
||||
All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.
|
||||
|
||||
There are two types of RKE cluster scan profiles:
|
||||
|
||||
- **Permissive:** This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
|
||||
- **Hardened:** This profile will not skip any tests, except for the non-applicable tests.
|
||||
|
||||
The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.
|
||||
|
||||
In order to pass the "Hardened" profile, you will need to follow the steps on the <a href="{{<baseurl>}}/rancher/v2.6/en/security/#rancher-hardening-guide" target="_blank">hardening guide</a> and use the `cluster.yml` defined in the hardening guide to provision a hardened cluster.
|
||||
|
||||
The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned:
|
||||
|
||||
The `rancher-cis-benchmark` supports the CIS 1.6 Benchmark version.
|
||||
|
||||
- For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
|
||||
- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters.
|
||||
- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.6 profile is the default.
|
||||
- For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.
|
||||
|
||||
# About Skipped and Not Applicable Tests
|
||||
|
||||
For a list of skipped and not applicable tests, refer to <a href="{{<baseurl>}}/rancher/v2.6/en/cis-scans/skipped-tests" target="_blank">this page.</a>
|
||||
|
||||
For now, only user-defined skipped tests are marked as skipped in the generated report.
|
||||
|
||||
Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.
|
||||
|
||||
# Roles-based Access Control
|
||||
|
||||
For information about permissions, refer to <a href="{{<baseurl>}}/rancher/v2.6/en/cis-scans/rbac" target="_blank">this page.</a>
|
||||
|
||||
# Configuration
|
||||
|
||||
For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to <a href="{{<baseurl>}}/rancher/v2.6/en/cis-scans/configuration" target="_blank">this page.</a>
|
||||
|
||||
# How-to Guides
|
||||
|
||||
- [Installing rancher-cis-benchmark](#installing-rancher-cis-benchmark)
|
||||
- [Uninstalling rancher-cis-benchmark](#uninstalling-rancher-cis-benchmark)
|
||||
- [Running a Scan](#running-a-scan)
|
||||
- [Running a Scan Periodically on a Schedule](#running-a-scan-periodically-on-a-schedule)
|
||||
- [Skipping Tests](#skipping-tests)
|
||||
- [Viewing Reports](#viewing-reports)
|
||||
- [Enabling Alerting for rancher-cis-benchmark](#enabling-alerting-for-rancher-cis-benchmark)
|
||||
- [Configuring Alerts for a Periodic Scan on a Schedule](#configuring-alerts-for-a-periodic-scan-on-a-schedule)
|
||||
- [Creating a Custom Benchmark Version for Running a Cluster Scan](#creating-a-custom-benchmark-version-for-running-a-cluster-scan)
|
||||
### Installing CIS Benchmark
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to install CIS Benchmark and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps & Marketplace > Charts**.
|
||||
1. Click **CIS Benchmark**
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
|
||||
|
||||
### Uninstalling CIS Benchmark
|
||||
|
||||
1. From the **Cluster Dashboard,** go to the left navigation bar and click **Apps & Marketplace > Installed Apps**.
|
||||
1. Go to the `cis-operator-system` namespace and check the boxes next to `rancher-cis-benchmark-crd` and `rancher-cis-benchmark`.
|
||||
1. Click **Delete** and confirm **Delete**.
|
||||
|
||||
**Result:** The `rancher-cis-benchmark` application is uninstalled.
|
||||
|
||||
### Running a Scan
|
||||
|
||||
When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.
|
||||
|
||||
Note: There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
|
||||
|
||||
To run a scan,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
|
||||
### Running a Scan Periodically on a Schedule
|
||||
|
||||
To run a ClusterScan on a schedule,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid <a href="https://en.wikipedia.org/wiki/Cron#CRON_expression" target="_blank">cron schedule expression</a> in the field **Schedule**.
|
||||
1. Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. The **Next Scan** value indicates the next time this scan will run again.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
You can also see the previous reports by choosing the report from the **Reports** dropdown on the scan detail page.
|
||||
|
||||
### Skipping Tests
|
||||
|
||||
CIS scans can be run using test profiles with user-defined skips.
|
||||
|
||||
To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Profile**.
|
||||
1. From here, you can create a profile in multiple ways. To make a new profile, click **Create** and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile and click **⋮ Clone**. If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the `skipTests` directive. You will also give the profile a name:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScanProfile
|
||||
metadata:
|
||||
annotations:
|
||||
meta.helm.sh/release-name: clusterscan-operator
|
||||
meta.helm.sh/release-namespace: cis-operator-system
|
||||
labels:
|
||||
app.kubernetes.io/managed-by: Helm
|
||||
name: "<example-profile>"
|
||||
spec:
|
||||
benchmarkVersion: cis-1.5
|
||||
skipTests:
|
||||
- "1.1.20"
|
||||
- "1.1.21"
|
||||
```
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A new CIS scan profile is created.
|
||||
|
||||
When you [run a scan](#running-a-scan) that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as `Skip`.
|
||||
|
||||
### Viewing Reports
|
||||
|
||||
To view the generated CIS scan reports,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
|
||||
|
||||
One can download the report from the Scans list or from the scan detail page.
|
||||
|
||||
### Enabling Alerting for rancher-cis-benchmark
|
||||
|
||||
Alerts can be configured to be sent out for a scan that runs on a schedule.
|
||||
|
||||
> **Prerequisite:**
|
||||
>
|
||||
> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/configuration)
|
||||
>
|
||||
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
While installing or upgrading the `rancher-cis-benchmark` Helm chart, set the following flag to `true` in the `values.yaml`:
|
||||
|
||||
```yaml
|
||||
alerts:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### Configuring Alerts for a Periodic Scan on a Schedule
|
||||
|
||||
It is possible to run a ClusterScan on a schedule.
|
||||
|
||||
A scheduled scan can also specify if you should receive alerts when the scan completes.
|
||||
|
||||
Alerts are supported only for a scan that runs on a schedule.
|
||||
|
||||
The CIS Benchmark application supports two types of alerts:
|
||||
|
||||
- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
|
||||
- Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state.
|
||||
|
||||
> **Prerequisite:**
|
||||
>
|
||||
> Before enabling alerts for `rancher-cis-benchmark`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/configuration)
|
||||
>
|
||||
> While configuring the routes for `rancher-cis-benchmark` alerts, you can specify the matching using the key-value pair `job: rancher-cis-scan`. An example route configuration is [here.]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/configuration/receiver/#example-route-config-for-cis-scan-alerts)
|
||||
|
||||
To configure alerts for a scan that runs on a schedule,
|
||||
|
||||
1. Please enable alerts on the `rancher-cis-benchmark` application (#enabling-alerting-for-rancher-cis-benchmark)
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a CIS scan and click **Explore**.
|
||||
1. Click **CIS Benchmark > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule**.
|
||||
1. Check the boxes next to the Alert types under **Alerting**.
|
||||
1. Optional: Choose a **Retention Count**, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
### Creating a Custom Benchmark Version for Running a Cluster Scan
|
||||
|
||||
There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
|
||||
|
||||
It is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application.
|
||||
|
||||
For details, see [this page.](./custom-benchmark)
|
||||
@@ -1,98 +0,0 @@
|
||||
---
|
||||
title: Configuration
|
||||
weight: 3
|
||||
---
|
||||
|
||||
This configuration reference is intended to help you manage the custom resources created by the `rancher-cis-benchmark` application. These resources are used for performing CIS scans on a cluster, skipping tests, setting the test profile that will be used during a scan, and other customization.
|
||||
|
||||
To configure the custom resources, go to the **Cluster Dashboard** To configure the CIS scans,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to configure CIS scans and click **Explore**.
|
||||
1. In the left navigation bar, click **CIS Benchmark**.
|
||||
|
||||
### Scans
|
||||
|
||||
A scan is created to trigger a CIS scan on the cluster based on the defined profile. A report is created after the scan is completed.
|
||||
|
||||
When configuring a scan, you need to define the name of the scan profile that will be used with the `scanProfileName` directive.
|
||||
|
||||
An example ClusterScan custom resource is below:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScan
|
||||
metadata:
|
||||
name: rke-cis
|
||||
spec:
|
||||
scanProfileName: rke-profile-hardened
|
||||
```
|
||||
|
||||
### Profiles
|
||||
|
||||
A profile contains the configuration for the CIS scan, which includes the benchmark version to use and any specific tests to skip in that benchmark.
|
||||
|
||||
> By default, a few ClusterScanProfiles are installed as part of the `rancher-cis-benchmark` chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles.
|
||||
|
||||
Users can clone the ClusterScanProfiles to create custom profiles.
|
||||
|
||||
Skipped tests are listed under the `skipTests` directive.
|
||||
|
||||
When you create a new profile, you will also need to give it a name.
|
||||
|
||||
An example `ClusterScanProfile` is below:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScanProfile
|
||||
metadata:
|
||||
annotations:
|
||||
meta.helm.sh/release-name: clusterscan-operator
|
||||
meta.helm.sh/release-namespace: cis-operator-system
|
||||
labels:
|
||||
app.kubernetes.io/managed-by: Helm
|
||||
name: "<example-profile>"
|
||||
spec:
|
||||
benchmarkVersion: cis-1.5
|
||||
skipTests:
|
||||
- "1.1.20"
|
||||
- "1.1.21"
|
||||
```
|
||||
|
||||
### Benchmark Versions
|
||||
|
||||
A benchmark version is the name of benchmark to run using `kube-bench`, as well as the valid configuration parameters for that benchmark.
|
||||
|
||||
A `ClusterScanBenchmark` defines the CIS `BenchmarkVersion` name and test configurations. The `BenchmarkVersion` name is a parameter provided to the `kube-bench` tool.
|
||||
|
||||
By default, a few `BenchmarkVersion` names and test configurations are packaged as part of the CIS scan application. When this feature is enabled, these default BenchmarkVersions will be automatically installed and available for users to create a ClusterScanProfile.
|
||||
|
||||
> If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks.
|
||||
|
||||
A ClusterScanBenchmark consists of the fields:
|
||||
|
||||
- `ClusterProvider`: This is the cluster provider name for which this benchmark is applicable. For example: RKE, EKS, GKE, etc. Leave it empty if this benchmark can be run on any cluster type.
|
||||
- `MinKubernetesVersion`: Specifies the cluster's minimum kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular Kubernetes version.
|
||||
- `MaxKubernetesVersion`: Specifies the cluster's maximum Kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular k8s version.
|
||||
|
||||
An example `ClusterScanBenchmark` is below:
|
||||
|
||||
```yaml
|
||||
apiVersion: cis.cattle.io/v1
|
||||
kind: ClusterScanBenchmark
|
||||
metadata:
|
||||
annotations:
|
||||
meta.helm.sh/release-name: clusterscan-operator
|
||||
meta.helm.sh/release-namespace: cis-operator-system
|
||||
creationTimestamp: "2020-08-28T18:18:07Z"
|
||||
generation: 1
|
||||
labels:
|
||||
app.kubernetes.io/managed-by: Helm
|
||||
name: cis-1.5
|
||||
resourceVersion: "203878"
|
||||
selfLink: /apis/cis.cattle.io/v1/clusterscanbenchmarks/cis-1.5
|
||||
uid: 309e543e-9102-4091-be91-08d7af7fb7a7
|
||||
spec:
|
||||
clusterProvider: ""
|
||||
minKubernetesVersion: 1.15.0
|
||||
```
|
||||
@@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Creating a Custom Benchmark Version for Running a Cluster Scan
|
||||
weight: 4
|
||||
---
|
||||
|
||||
Each Benchmark Version defines a set of test configuration files that define the CIS tests to be run by the <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> tool.
|
||||
The `rancher-cis-benchmark` application installs a few default Benchmark Versions which are listed under CIS Benchmark application menu.
|
||||
|
||||
But there could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.
|
||||
|
||||
It is now possible to create a custom Benchmark Version for running a cluster scan using the `rancher-cis-benchmark` application.
|
||||
|
||||
When a cluster scan is run, you need to select a Profile which points to a specific Benchmark Version.
|
||||
|
||||
Follow all the steps below to add a custom Benchmark Version and run a scan using it.
|
||||
|
||||
1. [Prepare the Custom Benchmark Version ConfigMap](#1-prepare-the-custom-benchmark-version-configmap)
|
||||
2. [Add a Custom Benchmark Version to a Cluster](#2-add-a-custom-benchmark-version-to-a-cluster)
|
||||
3. [Create a New Profile for the Custom Benchmark Version](#3-create-a-new-profile-for-the-custom-benchmark-version)
|
||||
4. [Run a Scan Using the Custom Benchmark Version](#4-run-a-scan-using-the-custom-benchmark-version)
|
||||
|
||||
### 1. Prepare the Custom Benchmark Version ConfigMap
|
||||
|
||||
To create a custom benchmark version, first you need to create a ConfigMap containing the benchmark version's config files and upload it to your Kubernetes cluster where you want to run the scan.
|
||||
|
||||
To prepare a custom benchmark version ConfigMap, suppose we want to add a custom Benchmark Version named `foo`.
|
||||
|
||||
1. Create a directory named `foo` and inside this directory, place all the config YAML files that the <a href="https://github.com/aquasecurity/kube-bench" target="_blank">kube-bench</a> tool looks for. For example, here are the config YAML files for a Generic CIS 1.5 Benchmark Version https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5
|
||||
1. Place the complete `config.yaml` file, which includes all the components that should be tested.
|
||||
1. Add the Benchmark version name to the `target_mapping` section of the `config.yaml`:
|
||||
|
||||
```yaml
|
||||
target_mapping:
|
||||
"foo":
|
||||
- "master"
|
||||
- "node"
|
||||
- "controlplane"
|
||||
- "etcd"
|
||||
- "policies"
|
||||
```
|
||||
1. Upload this directory to your Kubernetes Cluster by creating a ConfigMap:
|
||||
|
||||
```yaml
|
||||
kubectl create configmap -n <namespace> foo --from-file=<path to directory foo>
|
||||
```
|
||||
|
||||
### 2. Add a Custom Benchmark Version to a Cluster
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**.
|
||||
1. In the left navigation bar, click **CIS Benchmark > Benchmark Version**.
|
||||
1. Click **Create**.
|
||||
1. Enter the **Name** and a description for your custom benchmark version.
|
||||
1. Choose the cluster provider that your benchmark version applies to.
|
||||
1. Choose the ConfigMap you have uploaded from the dropdown.
|
||||
1. Add the minimum and maximum Kubernetes version limits applicable, if any.
|
||||
1. Click **Create**.
|
||||
|
||||
### 3. Create a New Profile for the Custom Benchmark Version
|
||||
|
||||
To run a scan using your custom benchmark version, you need to add a new Profile pointing to this benchmark version.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**.
|
||||
1. In the left navigation bar, click **CIS Benchmark > Profile**.
|
||||
1. Click **Create**.
|
||||
1. Provide a **Name** and description. In this example, we name it `foo-profile`.
|
||||
1. Choose the Benchmark Version from the dropdown.
|
||||
1. Click **Create**.
|
||||
|
||||
### 4. Run a Scan Using the Custom Benchmark Version
|
||||
|
||||
Once the Profile pointing to your custom benchmark version `foo` has been created, you can create a new Scan to run the custom test configs in the Benchmark Version.
|
||||
|
||||
To run a scan,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**.
|
||||
1. In the left navigation bar, click **CIS Benchmark > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose the new cluster scan profile.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Roles-based Access Control
|
||||
shortTitle: RBAC
|
||||
weight: 3
|
||||
---
|
||||
|
||||
This section describes the permissions required to use the rancher-cis-benchmark App.
|
||||
|
||||
The rancher-cis-benchmark is a cluster-admin only feature by default.
|
||||
|
||||
However, the `rancher-cis-benchmark` chart installs these two default `ClusterRoles`:
|
||||
|
||||
- cis-admin
|
||||
- cis-view
|
||||
|
||||
In Rancher, only cluster owners and global administrators have `cis-admin` access by default.
|
||||
|
||||
Note: If you were using the `cis-edit` role added in Rancher v2.5 setup, it has now been removed since
|
||||
Rancher v2.5.2 because it essentially is same as `cis-admin`. If you happen to create any clusterrolebindings
|
||||
for `cis-edit`, please update them to use `cis-admin` ClusterRole instead.
|
||||
|
||||
# Cluster-Admin Access
|
||||
|
||||
Rancher CIS Scans is a cluster-admin only feature by default.
|
||||
This means only the Rancher global admins, and the cluster’s cluster-owner can:
|
||||
|
||||
- Install/Uninstall the rancher-cis-benchmark App
|
||||
- See the navigation links for CIS Benchmark CRDs - ClusterScanBenchmarks, ClusterScanProfiles, ClusterScans
|
||||
- List the default ClusterScanBenchmarks and ClusterScanProfiles
|
||||
- Create/Edit/Delete new ClusterScanProfiles
|
||||
- Create/Edit/Delete a new ClusterScan to run the CIS scan on the cluster
|
||||
- View and Download the ClusterScanReport created after the ClusterScan is complete
|
||||
|
||||
|
||||
# Summary of Default Permissions for Kubernetes Default Roles
|
||||
|
||||
The rancher-cis-benchmark creates three `ClusterRoles` and adds the CIS Benchmark CRD access to the following default K8s `ClusterRoles`:
|
||||
|
||||
| ClusterRole created by chart | Default K8s ClusterRole | Permissions given with Role
|
||||
| ------------------------------| ---------------------------| ---------------------------|
|
||||
| `cis-admin` | `admin`| Ability to CRUD clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR
|
||||
| `cis-view` | `view `| Ability to List(R) clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR
|
||||
|
||||
|
||||
By default only cluster-owner role will have ability to manage and use `rancher-cis-benchmark` feature.
|
||||
|
||||
The other Rancher roles (cluster-member, project-owner, project-member) do not have any default permissions to manage and use rancher-cis-benchmark resources.
|
||||
|
||||
But if a cluster-owner wants to delegate access to other users, they can do so by creating ClusterRoleBindings between these users and the above CIS ClusterRoles manually.
|
||||
There is no automatic role aggregation supported for the `rancher-cis-benchmark` ClusterRoles.
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
title: Skipped and Not Applicable Tests
|
||||
weight: 3
|
||||
---
|
||||
|
||||
This section lists the tests that are skipped in the permissive test profile for RKE.
|
||||
|
||||
> All the tests that are skipped and not applicable on this page will be counted as Not Applicable in the v2.5 generated report. The skipped test count will only mention the user-defined skipped tests. This allows user-skipped tests to be distinguished from the tests that are skipped by default in the RKE permissive test profile.
|
||||
|
||||
# CIS Benchmark v1.5
|
||||
|
||||
### CIS Benchmark v1.5 Skipped Tests
|
||||
|
||||
| Number | Description | Reason for Skipping |
|
||||
| ---------- | ------------- | --------- |
|
||||
| 1.1.12 | Ensure that the etcd data directory ownership is set to etcd:etcd (Automated) | A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership. |
|
||||
| 1.2.6 | Ensure that the --kubelet-certificate-authority argument is set as appropriate (Automated) | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. |
|
||||
| 1.2.16 | Ensure that the admission control plugin PodSecurityPolicy is set (Automated) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 1.2.33 | Ensure that the --encryption-provider-config argument is set as appropriate (Manual) | Enabling encryption changes how data can be recovered as data is encrypted. |
|
||||
| 1.2.34 | Ensure that encryption providers are appropriately configured (Manual) | Enabling encryption changes how data can be recovered as data is encrypted. |
|
||||
| 4.2.6 | Ensure that the --protect-kernel-defaults argument is set to true (Automated) | System level configurations are required before provisioning the cluster in order for this argument to be set to true. |
|
||||
| 4.2.10 | Ensure that the--tls-cert-file and --tls-private-key-file arguments are set as appropriate (Automated) | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. |
|
||||
| 5.1.5 | Ensure that default service accounts are not actively used. (Automated) | Kubernetes provides default service accounts to be used. |
|
||||
| 5.2.2 | Minimize the admission of containers wishing to share the host process ID namespace (Automated) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.3 | Minimize the admission of containers wishing to share the host IPC namespace (Automated) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.4 | Minimize the admission of containers wishing to share the host network namespace (Automated) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.5 | Minimize the admission of containers with allowPrivilegeEscalation (Automated) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.3.2 | Ensure that all Namespaces have Network Policies defined (Automated) | Enabling Network Policies can prevent certain applications from communicating with each other. |
|
||||
| 5.6.4 | The default namespace should not be used (Automated) | Kubernetes provides a default namespace. |
|
||||
|
||||
### CIS Benchmark v1.5 Not Applicable Tests
|
||||
|
||||
| Number | Description | Reason for being not applicable |
|
||||
| ---------- | ------------- | --------- |
|
||||
| 1.1.1 | Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.2 | Ensure that the API server pod specification file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.3 | Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.4 | Ensure that the controller manager pod specification file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.5 | Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.6 | Ensure that the scheduler pod specification file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.7 | Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.8 | Ensure that the etcd pod specification file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.13 | Ensure that the admin.conf file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes. |
|
||||
| 1.1.14 | Ensure that the admin.conf file ownership is set to root:root (Automated) | Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes. |
|
||||
| 1.1.15 | Ensure that the scheduler.conf file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.16 | Ensure that the scheduler.conf file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.17 | Ensure that the controller-manager.conf file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.18 | Ensure that the controller-manager.conf file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.3.6 | Ensure that the RotateKubeletServerCertificate argument is set to true (Automated) | Clusters provisioned by RKE handles certificate rotation directly through RKE. |
|
||||
| 4.1.1 | Ensure that the kubelet service file permissions are set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.2 | Ensure that the kubelet service file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.9 | Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Automated) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.10 | Ensure that the kubelet configuration file ownership is set to root:root (Automated) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time. |
|
||||
| 4.2.12 | Ensure that the RotateKubeletServerCertificate argument is set to true (Automated) | Clusters provisioned by RKE handles certificate rotation directly through RKE. |
|
||||
@@ -1,133 +0,0 @@
|
||||
---
|
||||
title: CLI with Rancher
|
||||
description: Interact with Rancher using command line interface (CLI) tools from your workstation.
|
||||
weight: 21
|
||||
---
|
||||
|
||||
- [Rancher CLI](#rancher-cli)
|
||||
- [Download Rancher CLI](#download-rancher-cli)
|
||||
- [Requirements](#requirements)
|
||||
- [CLI Authentication](#cli-authentication)
|
||||
- [Project Selection](#project-selection)
|
||||
- [Commands](#commands)
|
||||
- [Rancher CLI Help](#rancher-cli-help)
|
||||
- [Limitations](#limitations)
|
||||
- [kubectl](#kubectl)
|
||||
- [kubectl Utility](#kubectl-utility)
|
||||
- [Authentication with kubectl and kubeconfig Tokens with TTL](#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl)
|
||||
|
||||
# Rancher CLI
|
||||
|
||||
The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.
|
||||
|
||||
### Download Rancher CLI
|
||||
|
||||
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary.
|
||||
|
||||
1. In the upper left corner, click **☰**.
|
||||
1. At the bottom, click **v2.6.x**, where **v2.6.x** is a hyperlinked text indicating the installed Rancher version.
|
||||
1. Under the **CLI Downloads section**, there are links to download the binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary.
|
||||
|
||||
### Requirements
|
||||
|
||||
After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:
|
||||
|
||||
- Your Rancher Server URL, which is used to connect to Rancher Server.
|
||||
- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key]({{<baseurl>}}/rancher/v2.6/en/user-settings/api-keys/).
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `<BEARER_TOKEN>` and `<SERVER_URL>` with your information):
|
||||
|
||||
```bash
|
||||
$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>
|
||||
```
|
||||
|
||||
If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.
|
||||
|
||||
### Project Selection
|
||||
|
||||
Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project.
|
||||
|
||||
**Example: `./rancher context switch` Output**
|
||||
```
|
||||
User:rancher-cli-directory user$ ./rancher context switch
|
||||
NUMBER CLUSTER NAME PROJECT ID PROJECT NAME
|
||||
1 cluster-2 c-7q96s:p-h4tmb project-2
|
||||
2 cluster-2 c-7q96s:project-j6z6d Default
|
||||
3 cluster-1 c-lchzv:p-xbpdt project-1
|
||||
4 cluster-1 c-lchzv:project-s2mch Default
|
||||
Select a Project:
|
||||
```
|
||||
|
||||
After you enter a number, the console displays a message that you've changed projects.
|
||||
|
||||
```
|
||||
INFO[0005] Setting new context to project project-1
|
||||
INFO[0005] Saving config to /Users/markbishop/.rancher/cli2.json
|
||||
```
|
||||
|
||||
Ensure you can run `rancher kubectl get pods` successfully.
|
||||
|
||||
### Commands
|
||||
|
||||
The following commands are available for use in Rancher CLI.
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `apps, [app]` | Performs operations on catalog applications (i.e., individual [Helm charts](https://docs.helm.sh/developing_charts/)) or Rancher charts. |
|
||||
| `catalog` | Performs operations on [catalogs]({{<baseurl>}}/rancher/v2.6/en/helm-charts/). |
|
||||
| `clusters, [cluster]` | Performs operations on your [clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/). |
|
||||
| `context` | Switches between Rancher [projects]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/). For an example, see [Project Selection](#project-selection). |
|
||||
| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/) and [workloads]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/workloads/)). Specify resources by name or ID. |
|
||||
| `kubectl` |Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). |
|
||||
| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). |
|
||||
| `namespaces, [namespace]` |Performs operations on namespaces. |
|
||||
| `nodes, [node]` |Performs operations on nodes. |
|
||||
| `projects, [project]` | Performs operations on [projects]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/). |
|
||||
| `ps` | Displays [workloads]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/workloads) in a project. |
|
||||
| `settings, [setting]` | Shows the current settings for your Rancher Server. |
|
||||
| `ssh` | Connects to one of your cluster nodes using the SSH protocol. |
|
||||
| `help, [h]` | Shows a list of commands or help for one command. |
|
||||
|
||||
|
||||
### Rancher CLI Help
|
||||
|
||||
Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands.
|
||||
|
||||
All commands accept the `--help` flag, which documents each command's usage.
|
||||
|
||||
### Limitations
|
||||
|
||||
The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/).
|
||||
|
||||
# kubectl
|
||||
|
||||
Interact with Rancher using kubectl.
|
||||
|
||||
### kubectl Utility
|
||||
|
||||
Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
|
||||
Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file.
|
||||
|
||||
Run `kubectl cluster-info` or `kubectl get pods` successfully.
|
||||
|
||||
### Authentication with kubectl and kubeconfig Tokens with TTL
|
||||
|
||||
_Requirements_
|
||||
|
||||
If admins have [enforced TTL on kubeconfig tokens]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](../cli) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
|
||||
`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.
|
||||
|
||||
This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:
|
||||
|
||||
1. Local
|
||||
2. Active Directory (LDAP only)
|
||||
3. FreeIPA
|
||||
4. OpenLDAP
|
||||
5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth
|
||||
|
||||
When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server.
|
||||
The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../api/api-tokens/#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../api/api-tokens/#deleting-tokens).
|
||||
Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
|
||||
@@ -1,166 +0,0 @@
|
||||
---
|
||||
title: Backing up a Cluster
|
||||
weight: 2045
|
||||
---
|
||||
|
||||
In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/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
|
||||
|
||||
### Snapshot Components
|
||||
|
||||
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 restore a cluster from a snapshot:
|
||||
|
||||
- **Restore just the etcd contents:** This restore is similar to restoring to snapshots in Rancher before 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.
|
||||
|
||||
### Generating the Snapshot from etcd Nodes
|
||||
|
||||
For each etcd node in the cluster, the etcd cluster health is checked. If the node reports that the etcd cluster is healthy, a snapshot is created from it and optionally uploaded to S3.
|
||||
|
||||
The snapshot is stored in `/opt/rke/etcd-snapshots`. If the directory is configured on the nodes as a shared mount, it will be overwritten. On S3, the snapshot will always be from the last node that uploads it, as all etcd nodes upload it and the last will remain.
|
||||
|
||||
In the case when multiple etcd nodes exist, any created snapshot is created after the cluster has been health checked, so it can be considered a valid snapshot of the data in the etcd cluster.
|
||||
|
||||
### Snapshot Naming Conventions
|
||||
|
||||
The name of the snapshot is auto-generated. The `--name` option can be used to override the name of the snapshot when creating one-time snapshots with the RKE CLI.
|
||||
|
||||
When Rancher creates a snapshot of an RKE cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows:
|
||||
|
||||
- `m` stands for manual
|
||||
- `r` stands for recurring
|
||||
- `l` stands for local
|
||||
- `s` stands for S3
|
||||
|
||||
Some example snapshot names are:
|
||||
|
||||
- c-9dmxz-rl-8b2cx
|
||||
- c-9dmxz-ml-kr56m
|
||||
- c-9dmxz-ms-t6bjb
|
||||
- c-9dmxz-rs-8gxc8
|
||||
|
||||
### How Restoring from a Snapshot Works
|
||||
|
||||
On restore, the following process is used:
|
||||
|
||||
1. The snapshot is retrieved from S3, if S3 is configured.
|
||||
2. The snapshot is unzipped (if zipped).
|
||||
3. One of the etcd nodes in the cluster serves that snapshot file to the other nodes.
|
||||
4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore.
|
||||
5. The cluster is restored and post-restore actions will be done in the cluster.
|
||||
|
||||
# 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.6/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 | 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 | Time in hours between recurring snapshots| 12 hours |
|
||||
| Recurring etcd Snapshot 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 upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, navigate to the cluster where you want to take a one-time snapshot.
|
||||
1. Click **⋮ > Take Snapshot**.
|
||||
|
||||
**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.6/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 ||
|
||||
|
||||
### Using a custom CA certificate for S3
|
||||
|
||||
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 upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click its name.
|
||||
1. Click the **Snapshots** tab to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
|
||||
|
||||
# Safe Timestamps
|
||||
|
||||
Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable.
|
||||
|
||||
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 before v2.2.0, after upgrading Rancher, you must [edit the cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before 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.6/en/cluster-admin/restoring-etcd/).
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
title: Certificate Rotation
|
||||
weight: 2040
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
> **Warning:** Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window.
|
||||
|
||||
By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted.
|
||||
|
||||
Certificates can be rotated for the following services:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="RKE">
|
||||
|
||||
- etcd
|
||||
- kubelet (node certificate)
|
||||
- kubelet (serving certificate, if [enabled]({{<baseurl>}}/rke/latest/en/config-options/services/#kubelet-options))
|
||||
- kube-apiserver
|
||||
- kube-proxy
|
||||
- kube-scheduler
|
||||
- kube-controller-manager
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE2">
|
||||
|
||||
- admin
|
||||
- api-server
|
||||
- controller-manager
|
||||
- scheduler
|
||||
- rke2-controller
|
||||
- rke2-server
|
||||
- cloud-controller
|
||||
- etcd
|
||||
- auth-proxy
|
||||
- kubelet
|
||||
- kube-proxy
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> **Note:** For users who didn't rotate their webhook certificates, and they have expired after one year, please see this [page]({{<baseurl>}}/rancher/v2.6/en/troubleshooting/expired-webhook-certificates/) for help.
|
||||
|
||||
|
||||
### Certificate Rotation
|
||||
|
||||
Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster you want to rotate certificates for amd click **⋮ > Rotate Certificates**.
|
||||
1. Select which certificates that you want to rotate.
|
||||
|
||||
* Rotate all Service certificates (keep the same CA)
|
||||
* Rotate an individual service and choose one of the services from the drop-down menu
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
**Results:** The selected certificates will be rotated and the related services will be restarted to start using the new certificate.
|
||||
|
||||
### Additional Notes
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="RKE">
|
||||
|
||||
Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher launched Kubernetes clusters.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE2">
|
||||
|
||||
In RKE2, both etcd and control plane nodes are treated as the same `server` concept. As such, when rotating certificates of services specific to either of these components will result in certificates being rotated on both. The certificates will only change for the specified service, but you will see nodes for both components go into an updating state. You may also see worker only nodes go into an updating state. This is to restart the workers after a certificate change to ensure they get the latest client certs.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
-285
@@ -1,285 +0,0 @@
|
||||
---
|
||||
title: Removing Kubernetes Components from Nodes
|
||||
description: Learn about cluster cleanup when removing nodes from your Rancher-launched Kubernetes cluster. What is removed, how to do it manually
|
||||
weight: 2055
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
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 install Kubernetes on new nodes in an infrastructure provider, 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] | [Registered 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.6/en/cluster-provisioning/rke-clusters/node-pools/
|
||||
[2]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes/
|
||||
[3]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/
|
||||
[4]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-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 Registered Clusters
|
||||
|
||||
For registered 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 registered 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 registered into Rancher.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="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 a registered 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 registered clusters in [What Gets Removed?](#what-gets-removed) are deleted.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="By Script">
|
||||
|
||||
Rather than cleaning registered cluster nodes using the Rancher UI, you can run a script instead.
|
||||
|
||||
>**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 registered clusters in [What Gets Removed?](#what-gets-removed) are deleted.
|
||||
|
||||
</TabItem>
|
||||
</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
|
||||
```
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
title: Cloning Clusters
|
||||
weight: 2035
|
||||
---
|
||||
|
||||
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 registered clusters is not supported.
|
||||
|
||||
| Cluster Type | Cloneable? |
|
||||
|----------------------------------|---------------|
|
||||
| [Nodes Hosted by Infrastructure Provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/) | ✓ |
|
||||
| [Hosted Kubernetes Providers]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/) | ✓ |
|
||||
| [Custom Cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes) | ✓ |
|
||||
| [Registered Cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-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.6/en/cli). Remember to [create an API bearer token]({{<baseurl>}}/rancher/v2.6/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:** 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.6/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.
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: How the Authorized Cluster Endpoint Works
|
||||
weight: 2015
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
If admins have [enforced TTL on kubeconfig tokens]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens/#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires [rancher cli]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/cluster-access/ace) to be present in your PATH.
|
||||
|
||||
|
||||
### Two Authentication Methods for RKE Clusters
|
||||
|
||||
If the cluster is not an [RKE cluster,]({{<baseurl>}}/rancher/v2.6/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.6/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.6/en/overview/architecture/#4-authorized-cluster-endpoint) which is only available for [RKE clusters.]({{<baseurl>}}/rancher/v2.6/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:
|
||||
|
||||
| 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` |
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Cluster Access
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This section is about what tools can be used to access clusters managed by Rancher.
|
||||
|
||||
For information on how to give users permission to access a cluster, see the section on [adding users to clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/cluster-access/cluster-members/)
|
||||
|
||||
For more information on roles-based access control, see [this section.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/)
|
||||
|
||||
For information on how to set up an authentication system, see [this section.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/)
|
||||
|
||||
|
||||
### 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.6/en/cluster-admin/cluster-access/kubectl/).
|
||||
- **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](./kubectl/).
|
||||
|
||||
### Rancher CLI
|
||||
|
||||
You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI]({{<baseurl>}}/rancher/v2.6/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.6/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.
|
||||
-52
@@ -1,52 +0,0 @@
|
||||
---
|
||||
title: Adding Users to Clusters
|
||||
weight: 2020
|
||||
---
|
||||
|
||||
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.6/en/cluster-admin/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. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster you want to add members to and click **⋮ > Edit Config**.
|
||||
1. In the **Member Roles** tab, click **Add Member**.
|
||||
1. 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.6/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.6/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.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
|
||||
|
||||
1. Assign the user or group **Cluster** roles.
|
||||
|
||||
[What are Cluster Roles?]({{<baseurl>}}/rancher/v2.6/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.6/en/admin-settings/rbac/default-custom-roles/).
|
||||
> - To remove roles from the list, [Lock/Unlock Roles]({{<baseurl>}}/rancher/v2.6/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.
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
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: 2010
|
||||
---
|
||||
|
||||
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. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster you want to access with kubectl and click **Explore**.
|
||||
1. In the top navigation menu, click the **Kubectl Shell** button. 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. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you want to access with kubectl and click **Explore**.
|
||||
1. In the top navigation bar, click **Download KubeConfig** button.
|
||||
1. Save the YAML 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.6/en/cluster-provisioning/rke-clusters)
|
||||
|
||||
This method is only available for RKE clusters that have the [authorized cluster endpoint]({{<baseurl>}}/rancher/v2.6/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.6/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
|
||||
```
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Cluster Administration
|
||||
weight: 8
|
||||
---
|
||||
|
||||
After you provision a cluster in Rancher, you can begin using powerful Kubernetes features to deploy and scale your containerized applications in development, testing, or production environments.
|
||||
|
||||
This page covers the following topics:
|
||||
|
||||
- [Switching between clusters](#switching-between-clusters)
|
||||
- [Managing clusters in Rancher](#managing-clusters-in-rancher)
|
||||
- [Configuring tools](#configuring-tools)
|
||||
|
||||
> 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.6/en/overview/concepts) page.
|
||||
|
||||
## Managing Clusters in Rancher
|
||||
|
||||
After clusters have been [provisioned into Rancher]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/), [cluster owners]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) will need to manage these clusters. There are many different options of how to manage your cluster.
|
||||
|
||||
import ClusterCapabilitiesTable from '/rancher/v2.6/en/shared-files/_cluster-capabilities-table.md';
|
||||
|
||||
<ClusterCapabilitiesTable />
|
||||
|
||||
## Configuring Tools
|
||||
|
||||
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:
|
||||
|
||||
- Alerts
|
||||
- Notifiers
|
||||
- Logging
|
||||
- Monitoring
|
||||
- Istio Service Mesh
|
||||
- OPA Gatekeeper
|
||||
|
||||
Tools can be installed through **Apps & Marketplace.**
|
||||
@@ -1,580 +0,0 @@
|
||||
---
|
||||
title: Cluster Autoscaler with AWS EC2 Auto Scaling Groups
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This guide will show you how to install and use [Kubernetes cluster-autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/) on Rancher custom clusters using AWS EC2 Auto Scaling Groups.
|
||||
|
||||
We are going to install a Rancher RKE custom cluster with a fixed number of nodes with the etcd and controlplane roles, and a variable nodes with the worker role, managed by `cluster-autoscaler`.
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [1. Create a Custom Cluster](#1-create-a-custom-cluster)
|
||||
- [2. Configure the Cloud Provider](#2-configure-the-cloud-provider)
|
||||
- [3. Deploy Nodes](#3-deploy-nodes)
|
||||
- [4. Install cluster-autoscaler](#4-install-cluster-autoscaler)
|
||||
- [Parameters](#parameters)
|
||||
- [Deployment](#deployment)
|
||||
- [Testing](#testing)
|
||||
- [Generating Load](#generating-load)
|
||||
- [Checking Scale](#checking-scale)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
These elements are required to follow this guide:
|
||||
|
||||
* The Rancher server is up and running
|
||||
* You have an AWS EC2 user with proper permissions to create virtual machines, auto scaling groups, and IAM profiles and roles
|
||||
|
||||
### 1. Create a Custom Cluster
|
||||
|
||||
On Rancher server, we should create a custom k8s cluster v1.18.x. Be sure that cloud_provider name is set to `amazonec2`. Once cluster is created we need to get:
|
||||
|
||||
* clusterID: `c-xxxxx` will be used on EC2 `kubernetes.io/cluster/<clusterID>` instance tag
|
||||
* clusterName: will be used on EC2 `k8s.io/cluster-autoscaler/<clusterName>` instance tag
|
||||
* nodeCommand: will be added on EC2 instance user_data to include new nodes on cluster
|
||||
|
||||
```sh
|
||||
sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CHECKSUM> <roles>
|
||||
```
|
||||
|
||||
### 2. Configure the Cloud Provider
|
||||
|
||||
On AWS EC2, we should create a few objects to configure our system. We've defined three distinct groups and IAM profiles to configure on AWS.
|
||||
|
||||
1. Autoscaling group: Nodes that will be part of the EC2 Auto Scaling Group (ASG). The ASG will be used by `cluster-autoscaler` to scale up and down.
|
||||
* IAM profile: Required by k8s nodes where cluster-autoscaler will be running. It is recommended for Kubernetes master nodes. This profile is called `K8sAutoscalerProfile`.
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"autoscaling:DescribeAutoScalingGroups",
|
||||
"autoscaling:DescribeAutoScalingInstances",
|
||||
"autoscaling:DescribeLaunchConfigurations",
|
||||
"autoscaling:SetDesiredCapacity",
|
||||
"autoscaling:TerminateInstanceInAutoScalingGroup",
|
||||
"autoscaling:DescribeTags",
|
||||
"autoscaling:DescribeLaunchConfigurations",
|
||||
"ec2:DescribeLaunchTemplateVersions"
|
||||
],
|
||||
"Resource": [
|
||||
"*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. Master group: Nodes that will be part of the Kubernetes etcd and/or control planes. This will be out of the ASG.
|
||||
* IAM profile: Required by the Kubernetes cloud_provider integration. Optionally, `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` can be used instead [using-aws-credentials.](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md#using-aws-credentials) This profile is called `K8sMasterProfile`.
|
||||
|
||||
```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",
|
||||
"ecr:GetAuthorizationToken",
|
||||
"ecr:BatchCheckLayerAvailability",
|
||||
"ecr:GetDownloadUrlForLayer",
|
||||
"ecr:GetRepositoryPolicy",
|
||||
"ecr:DescribeRepositories",
|
||||
"ecr:ListImages",
|
||||
"ecr:BatchGetImage",
|
||||
"kms:DescribeKey"
|
||||
],
|
||||
"Resource": [
|
||||
"*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* IAM role: `K8sMasterRole: [K8sMasterProfile,K8sAutoscalerProfile]`
|
||||
* Security group: `K8sMasterSg` More info at[RKE ports (custom nodes tab)]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/ports/#downstream-kubernetes-cluster-nodes)
|
||||
* Tags:
|
||||
`kubernetes.io/cluster/<clusterID>: owned`
|
||||
* User data: `K8sMasterUserData` Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add etcd+controlplane node to the k8s cluster
|
||||
|
||||
```sh
|
||||
#!/bin/bash -x
|
||||
|
||||
cat <<EOF > /etc/sysctl.d/90-kubelet.conf
|
||||
vm.overcommit_memory = 1
|
||||
vm.panic_on_oom = 0
|
||||
kernel.panic = 10
|
||||
kernel.panic_on_oops = 1
|
||||
kernel.keys.root_maxkeys = 1000000
|
||||
kernel.keys.root_maxbytes = 25000000
|
||||
EOF
|
||||
sysctl -p /etc/sysctl.d/90-kubelet.conf
|
||||
|
||||
curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
|
||||
sudo usermod -aG docker ubuntu
|
||||
|
||||
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
|
||||
PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
|
||||
PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
|
||||
K8S_ROLES="--etcd --controlplane"
|
||||
|
||||
sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}
|
||||
```
|
||||
|
||||
3. Worker group: Nodes that will be part of the k8s worker plane. Worker nodes will be scaled by cluster-autoscaler using the ASG.
|
||||
* IAM profile: Provides cloud_provider worker integration.
|
||||
This profile is called `K8sWorkerProfile`.
|
||||
|
||||
```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": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* IAM role: `K8sWorkerRole: [K8sWorkerProfile]`
|
||||
* Security group: `K8sWorkerSg` More info at [RKE ports (custom nodes tab)]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/ports/#downstream-kubernetes-cluster-nodes)
|
||||
* Tags:
|
||||
* `kubernetes.io/cluster/<clusterID>: owned`
|
||||
* `k8s.io/cluster-autoscaler/<clusterName>: true`
|
||||
* `k8s.io/cluster-autoscaler/enabled: true`
|
||||
* User data: `K8sWorkerUserData` Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add worker node to the k8s cluster
|
||||
|
||||
```sh
|
||||
#!/bin/bash -x
|
||||
|
||||
cat <<EOF > /etc/sysctl.d/90-kubelet.conf
|
||||
vm.overcommit_memory = 1
|
||||
vm.panic_on_oom = 0
|
||||
kernel.panic = 10
|
||||
kernel.panic_on_oops = 1
|
||||
kernel.keys.root_maxkeys = 1000000
|
||||
kernel.keys.root_maxbytes = 25000000
|
||||
EOF
|
||||
sysctl -p /etc/sysctl.d/90-kubelet.conf
|
||||
|
||||
curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
|
||||
sudo usermod -aG docker ubuntu
|
||||
|
||||
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
|
||||
PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
|
||||
PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
|
||||
K8S_ROLES="--worker"
|
||||
|
||||
sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKCSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}
|
||||
```
|
||||
|
||||
More info is at [RKE clusters on AWS]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/amazon/) and [Cluster Autoscaler on AWS.](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md)
|
||||
|
||||
### 3. Deploy Nodes
|
||||
|
||||
Once we've configured AWS, let's create VMs to bootstrap our cluster:
|
||||
|
||||
* master (etcd+controlplane): Depending your needs, deploy three master instances with proper size. More info is at [the recommendations for production-ready clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/production/)
|
||||
* IAM role: `K8sMasterRole`
|
||||
* Security group: `K8sMasterSg`
|
||||
* Tags:
|
||||
* `kubernetes.io/cluster/<clusterID>: owned`
|
||||
* User data: `K8sMasterUserData`
|
||||
|
||||
* worker: Define an ASG on EC2 with the following settings:
|
||||
* Name: `K8sWorkerAsg`
|
||||
* IAM role: `K8sWorkerRole`
|
||||
* Security group: `K8sWorkerSg`
|
||||
* Tags:
|
||||
* `kubernetes.io/cluster/<clusterID>: owned`
|
||||
* `k8s.io/cluster-autoscaler/<clusterName>: true`
|
||||
* `k8s.io/cluster-autoscaler/enabled: true`
|
||||
* User data: `K8sWorkerUserData`
|
||||
* Instances:
|
||||
* minimum: 2
|
||||
* desired: 2
|
||||
* maximum: 10
|
||||
|
||||
Once the VMs are deployed, you should have a Rancher custom cluster up and running with three master and two worker nodes.
|
||||
|
||||
### 4. Install Cluster-autoscaler
|
||||
|
||||
At this point, we should have rancher cluster up and running. We are going to install cluster-autoscaler on master nodes and `kube-system` namespace, following cluster-autoscaler recommendation.
|
||||
|
||||
#### Parameters
|
||||
|
||||
This table shows cluster-autoscaler parameters for fine tuning:
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|---|---|---|
|
||||
|cluster-name|-|Autoscaled cluster name, if available|
|
||||
|address|:8085|The address to expose Prometheus metrics|
|
||||
|kubernetes|-|Kubernetes master location. Leave blank for default|
|
||||
|kubeconfig|-|Path to kubeconfig file with authorization and master location information|
|
||||
|cloud-config|-|The path to the cloud provider configuration file. Empty string for no configuration file|
|
||||
|namespace|"kube-system"|Namespace in which cluster-autoscaler run|
|
||||
|scale-down-enabled|true|Should CA scale down the cluster|
|
||||
|scale-down-delay-after-add|"10m"|How long after scale up that scale down evaluation resumes|
|
||||
|scale-down-delay-after-delete|0|How long after node deletion that scale down evaluation resumes, defaults to scanInterval|
|
||||
|scale-down-delay-after-failure|"3m"|How long after scale down failure that scale down evaluation resumes|
|
||||
|scale-down-unneeded-time|"10m"|How long a node should be unneeded before it is eligible for scale down|
|
||||
|scale-down-unready-time|"20m"|How long an unready node should be unneeded before it is eligible for scale down|
|
||||
|scale-down-utilization-threshold|0.5|Sum of cpu or memory of all pods running on the node divided by node's corresponding allocatable resource, below which a node can be considered for scale down|
|
||||
|scale-down-gpu-utilization-threshold|0.5|Sum of gpu requests of all pods running on the node divided by node's allocatable resource, below which a node can be considered for scale down|
|
||||
|scale-down-non-empty-candidates-count|30|Maximum number of non empty nodes considered in one iteration as candidates for scale down with drain|
|
||||
|scale-down-candidates-pool-ratio|0.1|A ratio of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid|
|
||||
|scale-down-candidates-pool-min-count|50|Minimum number of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid|
|
||||
|node-deletion-delay-timeout|"2m"|Maximum time CA waits for removing delay-deletion.cluster-autoscaler.kubernetes.io/ annotations before deleting the node|
|
||||
|scan-interval|"10s"|How often cluster is reevaluated for scale up or down|
|
||||
|max-nodes-total|0|Maximum number of nodes in all node groups. Cluster autoscaler will not grow the cluster beyond this number|
|
||||
|cores-total|"0:320000"|Minimum and maximum number of cores in cluster, in the format `<min>:<max>.` Cluster autoscaler will not scale the cluster beyond these numbers|
|
||||
|memory-total|"0:6400000"|Minimum and maximum number of gigabytes of memory in cluster, in the format `<min>:<max>.` Cluster autoscaler will not scale the cluster beyond these numbers|
|
||||
cloud-provider|-|Cloud provider type|
|
||||
|max-bulk-soft-taint-count|10|Maximum number of nodes that can be tainted/untainted PreferNoSchedule at the same time. Set to 0 to turn off such tainting|
|
||||
|max-bulk-soft-taint-time|"3s"|Maximum duration of tainting/untainting nodes as PreferNoSchedule at the same time|
|
||||
|max-empty-bulk-delete|10|Maximum number of empty nodes that can be deleted at the same time|
|
||||
|max-graceful-termination-sec|600|Maximum number of seconds CA waits for pod termination when trying to scale down a node|
|
||||
|max-total-unready-percentage|45|Maximum percentage of unready nodes in the cluster. After this is exceeded, CA halts operations|
|
||||
|ok-total-unready-count|3|Number of allowed unready nodes, irrespective of max-total-unready-percentage|
|
||||
|scale-up-from-zero|true|Should CA scale up when there 0 ready nodes|
|
||||
|max-node-provision-time|"15m"|Maximum time CA waits for node to be provisioned|
|
||||
|nodes|-|sets min,max size and other configuration data for a node group in a format accepted by cloud provider. Can be used multiple times. Format: `<min>:<max>:<other...>`|
|
||||
|node-group-auto-discovery|-|One or more definition(s) of node group auto-discovery. A definition is expressed `<name of discoverer>:[<key>[=<value>]]`|
|
||||
|estimator|-|"binpacking"|Type of resource estimator to be used in scale up. Available values: ["binpacking"]|
|
||||
|expander|"random"|Type of node group expander to be used in scale up. Available values: `["random","most-pods","least-waste","price","priority"]`|
|
||||
|ignore-daemonsets-utilization|false|Should CA ignore DaemonSet pods when calculating resource utilization for scaling down|
|
||||
|ignore-mirror-pods-utilization|false|Should CA ignore Mirror pods when calculating resource utilization for scaling down|
|
||||
|write-status-configmap|true|Should CA write status information to a configmap|
|
||||
|max-inactivity|"10m"|Maximum time from last recorded autoscaler activity before automatic restart|
|
||||
|max-failing-time|"15m"|Maximum time from last recorded successful autoscaler run before automatic restart|
|
||||
|balance-similar-node-groups|false|Detect similar node groups and balance the number of nodes between them|
|
||||
|node-autoprovisioning-enabled|false|Should CA autoprovision node groups when needed|
|
||||
|max-autoprovisioned-node-group-count|15|The maximum number of autoprovisioned groups in the cluster|
|
||||
|unremovable-node-recheck-timeout|"5m"|The timeout before we check again a node that couldn't be removed before|
|
||||
|expendable-pods-priority-cutoff|-10|Pods with priority below cutoff will be expendable. They can be killed without any consideration during scale down and they don't cause scale up. Pods with null priority (PodPriority disabled) are non expendable|
|
||||
|regional|false|Cluster is regional|
|
||||
|new-pod-scale-up-delay|"0s"|Pods less than this old will not be considered for scale-up|
|
||||
|ignore-taint|-|Specifies a taint to ignore in node templates when considering to scale a node group|
|
||||
|balancing-ignore-label|-|Specifies a label to ignore in addition to the basic and cloud-provider set of labels when comparing if two node groups are similar|
|
||||
|aws-use-static-instance-list|false|Should CA fetch instance types in runtime or use a static list. AWS only|
|
||||
|profiling|false|Is debug/pprof endpoint enabled|
|
||||
|
||||
#### Deployment
|
||||
|
||||
Based on [cluster-autoscaler-run-on-master.yaml](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/examples/cluster-autoscaler-run-on-master.yaml) example, we've created our own `cluster-autoscaler-deployment.yaml` to use preferred [auto-discovery setup](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#auto-discovery-setup), updating tolerations, nodeSelector, image version and command config:
|
||||
|
||||
|
||||
```yml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
labels:
|
||||
k8s-addon: cluster-autoscaler.addons.k8s.io
|
||||
k8s-app: cluster-autoscaler
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRole
|
||||
metadata:
|
||||
name: cluster-autoscaler
|
||||
labels:
|
||||
k8s-addon: cluster-autoscaler.addons.k8s.io
|
||||
k8s-app: cluster-autoscaler
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["events", "endpoints"]
|
||||
verbs: ["create", "patch"]
|
||||
- apiGroups: [""]
|
||||
resources: ["pods/eviction"]
|
||||
verbs: ["create"]
|
||||
- apiGroups: [""]
|
||||
resources: ["pods/status"]
|
||||
verbs: ["update"]
|
||||
- apiGroups: [""]
|
||||
resources: ["endpoints"]
|
||||
resourceNames: ["cluster-autoscaler"]
|
||||
verbs: ["get", "update"]
|
||||
- apiGroups: [""]
|
||||
resources: ["nodes"]
|
||||
verbs: ["watch", "list", "get", "update"]
|
||||
- apiGroups: [""]
|
||||
resources:
|
||||
- "pods"
|
||||
- "services"
|
||||
- "replicationcontrollers"
|
||||
- "persistentvolumeclaims"
|
||||
- "persistentvolumes"
|
||||
verbs: ["watch", "list", "get"]
|
||||
- apiGroups: ["extensions"]
|
||||
resources: ["replicasets", "daemonsets"]
|
||||
verbs: ["watch", "list", "get"]
|
||||
- apiGroups: ["policy"]
|
||||
resources: ["poddisruptionbudgets"]
|
||||
verbs: ["watch", "list"]
|
||||
- apiGroups: ["apps"]
|
||||
resources: ["statefulsets", "replicasets", "daemonsets"]
|
||||
verbs: ["watch", "list", "get"]
|
||||
- apiGroups: ["storage.k8s.io"]
|
||||
resources: ["storageclasses", "csinodes"]
|
||||
verbs: ["watch", "list", "get"]
|
||||
- apiGroups: ["batch", "extensions"]
|
||||
resources: ["jobs"]
|
||||
verbs: ["get", "list", "watch", "patch"]
|
||||
- apiGroups: ["coordination.k8s.io"]
|
||||
resources: ["leases"]
|
||||
verbs: ["create"]
|
||||
- apiGroups: ["coordination.k8s.io"]
|
||||
resourceNames: ["cluster-autoscaler"]
|
||||
resources: ["leases"]
|
||||
verbs: ["get", "update"]
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
labels:
|
||||
k8s-addon: cluster-autoscaler.addons.k8s.io
|
||||
k8s-app: cluster-autoscaler
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["configmaps"]
|
||||
verbs: ["create","list","watch"]
|
||||
- apiGroups: [""]
|
||||
resources: ["configmaps"]
|
||||
resourceNames: ["cluster-autoscaler-status", "cluster-autoscaler-priority-expander"]
|
||||
verbs: ["delete", "get", "update", "watch"]
|
||||
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: cluster-autoscaler
|
||||
labels:
|
||||
k8s-addon: cluster-autoscaler.addons.k8s.io
|
||||
k8s-app: cluster-autoscaler
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: cluster-autoscaler
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
labels:
|
||||
k8s-addon: cluster-autoscaler.addons.k8s.io
|
||||
k8s-app: cluster-autoscaler
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: Role
|
||||
name: cluster-autoscaler
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: cluster-autoscaler
|
||||
namespace: kube-system
|
||||
labels:
|
||||
app: cluster-autoscaler
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: cluster-autoscaler
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cluster-autoscaler
|
||||
annotations:
|
||||
prometheus.io/scrape: 'true'
|
||||
prometheus.io/port: '8085'
|
||||
spec:
|
||||
serviceAccountName: cluster-autoscaler
|
||||
tolerations:
|
||||
- effect: NoSchedule
|
||||
operator: "Equal"
|
||||
value: "true"
|
||||
key: node-role.kubernetes.io/controlplane
|
||||
nodeSelector:
|
||||
node-role.kubernetes.io/controlplane: "true"
|
||||
containers:
|
||||
- image: eu.gcr.io/k8s-artifacts-prod/autoscaling/cluster-autoscaler:v1.18.1
|
||||
name: cluster-autoscaler
|
||||
resources:
|
||||
limits:
|
||||
cpu: 100m
|
||||
memory: 300Mi
|
||||
requests:
|
||||
cpu: 100m
|
||||
memory: 300Mi
|
||||
command:
|
||||
- ./cluster-autoscaler
|
||||
- --v=4
|
||||
- --stderrthreshold=info
|
||||
- --cloud-provider=aws
|
||||
- --skip-nodes-with-local-storage=false
|
||||
- --expander=least-waste
|
||||
- --node-group-auto-discovery=asg:tag=k8s.io/cluster-autoscaler/enabled,k8s.io/cluster-autoscaler/<clusterName>
|
||||
volumeMounts:
|
||||
- name: ssl-certs
|
||||
mountPath: /etc/ssl/certs/ca-certificates.crt
|
||||
readOnly: true
|
||||
imagePullPolicy: "Always"
|
||||
volumes:
|
||||
- name: ssl-certs
|
||||
hostPath:
|
||||
path: "/etc/ssl/certs/ca-certificates.crt"
|
||||
|
||||
```
|
||||
|
||||
Once the manifest file is prepared, deploy it in the Kubernetes cluster (Rancher UI can be used instead):
|
||||
|
||||
```sh
|
||||
kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml
|
||||
```
|
||||
|
||||
**Note:** Cluster-autoscaler deployment can also be set up using [manual configuration](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration)
|
||||
|
||||
# Testing
|
||||
|
||||
At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage `K8sWorkerAsg` ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true:
|
||||
|
||||
* There are pods that failed to run in the cluster due to insufficient resources. In this case, the cluster is scaled up.
|
||||
* There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes. In this case, the cluster is scaled down.
|
||||
|
||||
### Generating Load
|
||||
|
||||
We've prepared a `test-deployment.yaml` just to generate load on the Kubernetes cluster and see if cluster-autoscaler is working properly. The test deployment is requesting 1000m CPU and 1024Mi memory by three replicas. Adjust the requested resources and/or replica to be sure you exhaust the Kubernetes cluster resources:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app: hello-world
|
||||
name: hello-world
|
||||
spec:
|
||||
replicas: 3
|
||||
selector:
|
||||
matchLabels:
|
||||
app: hello-world
|
||||
strategy:
|
||||
rollingUpdate:
|
||||
maxSurge: 1
|
||||
maxUnavailable: 0
|
||||
type: RollingUpdate
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: hello-world
|
||||
spec:
|
||||
containers:
|
||||
- image: rancher/hello-world
|
||||
imagePullPolicy: Always
|
||||
name: hello-world
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
resources:
|
||||
limits:
|
||||
cpu: 1000m
|
||||
memory: 1024Mi
|
||||
requests:
|
||||
cpu: 1000m
|
||||
memory: 1024Mi
|
||||
```
|
||||
|
||||
Once the test deployment is prepared, deploy it in the Kubernetes cluster default namespace (Rancher UI can be used instead):
|
||||
|
||||
```
|
||||
kubectl -n default apply -f test-deployment.yaml
|
||||
```
|
||||
|
||||
### Checking Scale
|
||||
|
||||
Once the Kubernetes resources got exhausted, cluster-autoscaler should scale up worker nodes where pods failed to be scheduled. It should scale up until up until all pods became scheduled. You should see the new nodes on the ASG and on the Kubernetes cluster. Check the logs on the `kube-system` cluster-autoscaler pod.
|
||||
|
||||
Once scale up is checked, let check for scale down. To do it, reduce the replica number on the test deployment until you release enough Kubernetes cluster resources to scale down. You should see nodes disappear on the ASG and on the Kubernetes cluster. Check the logs on the `kube-system` cluster-autoscaler pod.
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: Cluster Autoscaler
|
||||
weight: 1
|
||||
---
|
||||
|
||||
In this section, you'll learn how to install and use the [Kubernetes cluster-autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/) on Rancher custom clusters using AWS EC2 Auto Scaling Groups.
|
||||
|
||||
The cluster autoscaler is a tool that automatically adjusts the size of the Kubernetes cluster when one of the following conditions is true:
|
||||
|
||||
* There are pods that failed to run in the cluster due to insufficient resources.
|
||||
* There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes.
|
||||
|
||||
To prevent your pod from being evicted, set a `priorityClassName: system-cluster-critical` property on your pod spec.
|
||||
|
||||
Cluster Autoscaler is designed to run on Kubernetes master nodes. It can run in the `kube-system` namespace. Cluster Autoscaler doesn't scale down nodes with non-mirrored `kube-system` pods running on them.
|
||||
|
||||
It's possible to run a customized deployment of Cluster Autoscaler on worker nodes, but extra care needs to be taken to ensure that Cluster Autoscaler remains up and running.
|
||||
|
||||
# Cloud Providers
|
||||
|
||||
Cluster Autoscaler provides support to distinct cloud providers. For more information, go to [cluster-autoscaler supported cloud providers.](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler#deployment)
|
||||
|
||||
### Setting up Cluster Autoscaler on Amazon Cloud Provider
|
||||
|
||||
For details on running the cluster autoscaler on Amazon cloud provider, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/cluster-autoscaler/amazon)
|
||||
-218
@@ -1,218 +0,0 @@
|
||||
---
|
||||
shortTitle: AKS Cluster Configuration
|
||||
title: AKS Cluster Configuration Reference
|
||||
weight: 4
|
||||
---
|
||||
|
||||
# Changes in Rancher v2.6
|
||||
|
||||
- Support for adding more than one node pool
|
||||
- Support for private clusters
|
||||
- Enabled autoscaling node pools
|
||||
- The AKS permissions are now configured in cloud credentials
|
||||
|
||||
# Role-based Access Control
|
||||
|
||||
When provisioning an AKS cluster in the Rancher UI, RBAC cannot be disabled. If role-based access control is disabled for the cluster in AKS, the cluster cannot be registered or imported into Rancher.
|
||||
|
||||
Rancher can configure member roles for AKS clusters in the same way as any other cluster. For more information, see the section on [role-based access control.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac)
|
||||
|
||||
# Cloud Credentials
|
||||
|
||||
> The configuration information in this section assumes you have already set up a service principal for Rancher. For step-by-step instructions for how to set up the service principal, see [this section.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/aks/#prerequisites-in-microsoft-azure)
|
||||
|
||||
### Subscription ID
|
||||
|
||||
To get the subscription ID, click **All Services** in the left navigation bar. Then click **Subscriptions**. Go to the name of the subscription that you want to associate with your Kubernetes cluster and copy the **Subscription ID**.
|
||||
|
||||
### Client ID
|
||||
|
||||
To get the client ID, go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal. The client ID is listed on the app registration detail page as **Application (client) ID**.
|
||||
|
||||
### Client Secret
|
||||
|
||||
You can't retrieve the client secret value after it is created, so if you don't already have a client secret value, you will need to create a new client secret.
|
||||
|
||||
To get a new client secret, go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal.
|
||||
|
||||
Then click **Certificates & secrets** and click **New client secret**. Click **Add**. Then copy the **Value** of the new client secret.
|
||||
|
||||
### Environment
|
||||
|
||||
Microsoft provides multiple [clouds](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest) for compliance with regional laws, which are available for your use:
|
||||
|
||||
- AzurePublicCloud
|
||||
- AzureGermanCloud
|
||||
- AzureChinaCloud
|
||||
- AzureUSGovernmentCloud
|
||||
|
||||
# Account Access
|
||||
|
||||
In this section you will need to select an existing Azure cloud credential or create a new one.
|
||||
|
||||
For help configuring your Azure cloud credential, see [this section.](#cloud-credentials)
|
||||
|
||||
# Cluster Location
|
||||
|
||||
Configure the cluster and node location. For more information on availability zones for AKS, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/availability-zones)
|
||||
|
||||
The high availability locations include multiple availability zones.
|
||||
|
||||
# Cluster Options
|
||||
|
||||
### Kubernetes Version
|
||||
|
||||
The available Kubernetes versions are dynamically fetched from the Azure API.
|
||||
|
||||
### Cluster Resource Group
|
||||
|
||||
A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group.
|
||||
|
||||
Use an existing resource group or enter a resource group name and one will be created for you.
|
||||
|
||||
Using a resource group containing an existing AKS cluster will create a new resource group. Azure AKS only allows one AKS cluster per resource group.
|
||||
|
||||
For information on managing resource groups, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)
|
||||
|
||||
### Linux Admin Username
|
||||
|
||||
The username used to create an SSH connection to the Linux nodes.
|
||||
|
||||
The default username for AKS nodes is `azureuser`.
|
||||
|
||||
### SSH Public Key
|
||||
|
||||
The key used to create an SSH connection to the Linux nodes.
|
||||
|
||||
### Tags
|
||||
|
||||
Cluster tags can be useful if your organization uses tags as a way to organize resources across multiple Azure services. These tags don't apply to resources within the cluster.
|
||||
|
||||
# Networking Options
|
||||
|
||||
### LoadBalancer SKU
|
||||
|
||||
Azure load balancers support both standard and basic SKUs (stock keeping units).
|
||||
|
||||
For a comparison of standard and basic load balancers, see the official [Azure documentation.](https://docs.microsoft.com/en-us/azure/load-balancer/skus#skus) Microsoft recommends the Standard load balancer.
|
||||
|
||||
The Standard load balancer is required if you have selected one or more availability zones, or if you have more than one node pool.
|
||||
|
||||
### Network Policy
|
||||
|
||||
All pods in an AKS cluster can send and receive traffic without limitations, by default. To improve security, you can define rules that control the flow of traffic. The Network Policy feature in Kubernetes lets you define rules for ingress and egress traffic between pods in a cluster.
|
||||
|
||||
Azure provides two ways to implement network policy. You choose a network policy option when you create an AKS cluster. The policy option can't be changed after the cluster is created:
|
||||
|
||||
- Azure's own implementation, called Azure Network Policies. The Azure network policy requires the Azure CNI.
|
||||
- Calico Network Policies, an open-source network and network security solution founded by [Tigera](https://www.tigera.io/).
|
||||
|
||||
You can also choose to have no network policy.
|
||||
|
||||
For more information about the differences between Azure and Calico network policies and their capabilities, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/use-network-policies#differences-between-azure-and-calico-policies-and-their-capabilities)
|
||||
|
||||
### DNS Prefix
|
||||
Enter a unique DNS prefix for your cluster's Kubernetes API server FQDN.
|
||||
|
||||
### Network Plugin
|
||||
There are two network plugins: kubenet and Azure CNI.
|
||||
|
||||
The [kubenet](https://kubernetes.io/docs/concepts/cluster-administration/network-plugins/#kubenet) Kubernetes plugin is the default configuration for AKS cluster creation. When kubenet is used, each node in the cluster receives a routable IP address. The pods use NAT to communicate with other resources outside the AKS cluster. This approach reduces the number of IP addresses you need to reserve in your network space for pods to use.
|
||||
|
||||
With the Azure CNI (advanced) networking plugin, pods get full virtual network connectivity and can be directly reached via their private IP address from connected networks. This plugin requires more IP address space.
|
||||
|
||||
For more information on the differences between kubenet and Azure CNI, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/concepts-network#compare-network-models)
|
||||
|
||||
### HTTP Application Routing
|
||||
|
||||
When enabled, the HTTP application routing add-on makes it easier to access applications deployed to the AKS cluster. It deploys two components: a [Kubernetes Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress/) and an [External-DNS](https://github.com/kubernetes-incubator/external-dns) controller.
|
||||
|
||||
For more information, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/http-application-routing)
|
||||
|
||||
### Set Authorized IP Ranges
|
||||
|
||||
You can secure access to the Kubernetes API server using [authorized IP address ranges.](https://docs.microsoft.com/en-us/azure/aks/api-server-authorized-ip-ranges#overview-of-api-server-authorized-ip-ranges)
|
||||
|
||||
The Kubernetes API server exposes the Kubernetes API. This component provides the interaction for management tools, such as kubectl. AKS provides a single-tenant cluster control plane with a dedicated API server. By default, the API server is assigned a public IP address, and you should control access to it using Kubernetes-based or Azure-based RBAC.
|
||||
|
||||
To secure access to the otherwise publicly accessible AKS control plane and API server, you can enable and use authorized IP ranges. These authorized IP ranges only allow defined IP address ranges to communicate with the API server.
|
||||
|
||||
However, even if you use authorized IP address ranges, you should still use Kubernetes RBAC or Azure RBAC to authorize users and the actions they request.
|
||||
|
||||
### Container Monitoring
|
||||
|
||||
Container monitoring gives you performance visibility by collecting memory and processor metrics from controllers, nodes, and containers that are available in Kubernetes through the Metrics API. Container logs are also collected. After you enable monitoring, metrics and logs are automatically collected for you through a containerized version of the Log Analytics agent for Linux. Metrics are written to the metrics store and log data is written to the logs store associated with your [Log Analytics](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/log-query-overview) workspace.
|
||||
|
||||
### Log Analytics Workspace Resource Group
|
||||
|
||||
The [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups) containing the Log Analytics Workspace. You must create at least one workspace to use Azure Monitor Logs.
|
||||
|
||||
### Log Analytics Workspace Name
|
||||
|
||||
Data collected by Azure Monitor Logs is stored in one or more [Log Analytics workspaces.](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/design-logs-deployment) The workspace defines the geographic location of the data, access rights defining which users can access data, and configuration settings such as the pricing tier and data retention.
|
||||
|
||||
You must create at least one workspace to use Azure Monitor Logs. A single workspace may be suffxicient for all of your monitoring data, or may choose to create multiple workspaces depending on your requirements. For example, you might have one workspace for your production data and another for testing.
|
||||
|
||||
For more information about Azure Monitor Logs, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/data-platform-logs)
|
||||
|
||||
### Support Private Kubernetes Service
|
||||
|
||||
Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint.
|
||||
|
||||
Rancher can connect to a private AKS cluster in one of two ways.
|
||||
|
||||
The first way to ensure that Rancher is running on the same [NAT](https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview) as the AKS nodes.
|
||||
|
||||
The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled.
|
||||
|
||||
> **Note:** Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region.
|
||||
|
||||
For more information about connecting to an AKS private cluster, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster)
|
||||
|
||||
# Node Pools
|
||||
|
||||
### Mode
|
||||
|
||||
The Azure interface allows users to specify whether a Primary Node Pool relies on either `system` (normally used for control planes) or `user` (what is most typically needed for Rancher).
|
||||
|
||||
For Primary Node Pools, you can specify Mode, OS, Count and Size.
|
||||
|
||||
System node pools always require running nodes, so they cannot be scaled below one node. At least one system node pool is required.
|
||||
|
||||
For subsequent node pools, the Rancher UI forces the default of User. User node pools allow you to scale to zero nodes. User node pools don't run any part of the Kubernetes controlplane.
|
||||
|
||||
AKS doesn't expose the nodes that run the Kubernetes controlplane components.
|
||||
|
||||
### Availability Zones
|
||||
|
||||
[Availability zones](https://docs.microsoft.com/en-us/azure/availability-zones/az-overview) are unique physical locations within a region. Each zone is made up of one or more data centers equipped with independent power, cooling, and networking.
|
||||
|
||||
Not all regions have support for availability zones. For a list of Azure regions with availability zones, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/availability-zones/az-region#azure-regions-with-availability-zones)
|
||||
|
||||
### VM Size
|
||||
|
||||
Choose a size for each VM in the node pool. For details about each VM size, see [this page.](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/)
|
||||
|
||||
### OS Disk Type
|
||||
|
||||
The nodes in the node pool can have either managed or ephemeral disks.
|
||||
|
||||
[Ephemeral OS disks](https://docs.microsoft.com/en-us/azure/virtual-machines/ephemeral-os-disks) are created on the local virtual machine storage and not saved to the remote Azure Storage. Ephemeral OS disks work well for stateless workloads, where applications are tolerant of individual VM failures, but are more affected by VM deployment time or reimaging the individual VM instances. With Ephemeral OS disk, you get lower read/write latency to the OS disk and faster VM reimage.
|
||||
|
||||
[Azure managed disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability.
|
||||
|
||||
### OS Disk Size
|
||||
|
||||
The size in GB for the disk for each node.
|
||||
|
||||
### Node Count
|
||||
The number of nodes in the node pool. The maximum number of nodes may be limited by your [Azure subscription.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)
|
||||
|
||||
### Max Pods Per Node
|
||||
The maximum number of pods per node defaults to 110 with a maximum of 250.
|
||||
|
||||
### Enable Auto Scaling
|
||||
|
||||
When auto scaling is enabled, you will need to enter a minimum and maximum node count.
|
||||
|
||||
When Auto Scaling is enabled, you can't manually scale the node pool. The scale is controlled by the AKS autoscaler.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Cluster Configuration
|
||||
weight: 2025
|
||||
---
|
||||
|
||||
After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster.
|
||||
|
||||
For information on editing cluster membership, go to [this page.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/cluster-access/cluster-members)
|
||||
|
||||
### Cluster Configuration References
|
||||
|
||||
The cluster configuration options depend on the type of Kubernetes cluster:
|
||||
|
||||
- [RKE Cluster Configuration](./rke-config-reference)
|
||||
- [RKE2 Cluster Configuration](./rke2-config-reference)
|
||||
- [K3s Cluster Configuration](./k3s-config-reference)
|
||||
- [EKS Cluster Configuration](./eks-config-reference)
|
||||
- [GKE Cluster Configuration](./gke-config-reference)
|
||||
- [AKS Cluster Configuration](./aks-config-reference)
|
||||
|
||||
### Cluster Management Capabilities by Cluster Type
|
||||
|
||||
The options and settings available for an existing cluster change based on the method that you used to provision it.
|
||||
|
||||
The following table summarizes the options and settings available for each cluster type:
|
||||
|
||||
import ClusterCapabilitiesTable from '/rancher/v2.6/en/shared-files/_cluster-capabilities-table.md';
|
||||
|
||||
<ClusterCapabilitiesTable />
|
||||
|
||||
-145
@@ -1,145 +0,0 @@
|
||||
---
|
||||
title: EKS Cluster Configuration Reference
|
||||
shortTitle: EKS Cluster Configuration
|
||||
weight: 2
|
||||
---
|
||||
|
||||
### Account Access
|
||||
|
||||
Complete each drop-down and field using the information obtained for your IAM policy.
|
||||
|
||||
| Setting | Description |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| Region | From the drop-down choose the geographical region in which to build your cluster. |
|
||||
| Cloud Credentials | Select the cloud credentials that you created for your IAM policy. For more information on creating cloud credentials in Rancher, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/user-settings/cloud-credentials/) |
|
||||
|
||||
### Service Role
|
||||
|
||||
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).
|
||||
|
||||
### Secrets Encryption
|
||||
|
||||
Optional: To encrypt secrets, select or enter a key created in [AWS Key Management Service (KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)
|
||||
|
||||
### API Server Endpoint Access
|
||||
|
||||
Configuring Public/Private API access is an advanced use case. For details, refer to the EKS cluster endpoint access control [documentation.](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html)
|
||||
|
||||
### Private-only API Endpoints
|
||||
|
||||
If you enable private and disable public API endpoint access when creating a cluster, then there is an extra step you must take in order for Rancher to connect to the cluster successfully. In this case, a pop-up will be displayed with a command that you will run on the cluster to register it with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster's Kubernetes API.
|
||||
|
||||
There are two ways to avoid this extra manual step:
|
||||
- You can create the cluster with both private and public API endpoint access on cluster creation. You can disable public access after the cluster is created and in an active state and Rancher will continue to communicate with the EKS cluster.
|
||||
- You can ensure that Rancher shares a subnet with the EKS cluster. Then security groups can be used to enable Rancher to communicate with the cluster's API endpoint. In this case, the command to register the cluster is not needed, and Rancher will be able to communicate with your cluster. For more information on configuring security groups, refer to the [security groups documentation](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html).
|
||||
|
||||
### Public Access Endpoints
|
||||
|
||||
Optionally limit access to the public endpoint via explicit CIDR blocks.
|
||||
|
||||
If you limit access to specific CIDR blocks, then it is recommended that you also enable the private access to avoid losing network communication to the cluster.
|
||||
|
||||
One of the following is required to enable private access:
|
||||
- Rancher's IP must be part of an allowed CIDR block
|
||||
- Private access should be enabled, and Rancher must share a subnet with the cluster and have network access to the cluster, which can be configured with a security group
|
||||
|
||||
For more information about public and private access to the cluster endpoint, refer to the [Amazon EKS documentation.](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html)
|
||||
|
||||
### Subnet
|
||||
|
||||
| Option | Description |
|
||||
| ------- | ------------ |
|
||||
| Standard: Rancher generated VPC and Subnet | While provisioning your cluster, Rancher generates a new VPC with 3 public subnets. |
|
||||
| Custom: Choose from your existing VPC and Subnets | While provisioning your cluster, Rancher configures your Control Plane and nodes to use a VPC and Subnet that you've already [created in AWS](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html). |
|
||||
|
||||
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)
|
||||
|
||||
### Security Group
|
||||
|
||||
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)
|
||||
|
||||
### Logging
|
||||
|
||||
Configure control plane logs to send to Amazon CloudWatch. You are charged the standard CloudWatch Logs data ingestion and storage costs for any logs sent to CloudWatch Logs from your clusters.
|
||||
|
||||
Each log type corresponds to a component of the Kubernetes control plane. To learn more about these components, see [Kubernetes Components](https://kubernetes.io/docs/concepts/overview/components/) in the Kubernetes documentation.
|
||||
|
||||
For more information on EKS control plane logging, refer to the official [documentation.](https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html)
|
||||
|
||||
### Managed Node Groups
|
||||
|
||||
Amazon EKS managed node groups automate the provisioning and lifecycle management of nodes (Amazon EC2 instances) for Amazon EKS Kubernetes clusters.
|
||||
|
||||
For more information about how node groups work and how they are configured, refer to the [EKS documentation.](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html)
|
||||
|
||||
#### Bring your own launch template
|
||||
|
||||
A launch template ID and version can be provided in order to easily configure the EC2 instances in a node group. If a launch template is provided, then none of the settings below will be configurable in Rancher. Therefore, using a launch template would require that all the necessary and desired settings from the list below would need to be specified in the launch template. Also note that if a launch template ID and version is provided, then only the template version can be updated. Using a new template ID would require creating a new managed node group.
|
||||
|
||||
| Option | Description | Required/Optional |
|
||||
| ------ | ----------- | ----------------- |
|
||||
| Instance Type | Choose the [hardware specs](https://aws.amazon.com/ec2/instance-types/) for the instance you're provisioning. | Required |
|
||||
| Image ID | Specify a custom AMI for the nodes. Custom AMIs used with EKS must be [configured properly](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/) | Optional |
|
||||
| Node Volume Size | The launch template must specify an EBS volume with the desired size | Required |
|
||||
| SSH Key | A key to be added to the instances to provide SSH access to the nodes | Optional |
|
||||
| User Data | Cloud init script in [MIME multi-part format](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-user-data) | Optional |
|
||||
| Instance Resource Tags | Tag each EC2 instance in the node group | Optional |
|
||||
|
||||
#### Rancher-managed launch templates
|
||||
|
||||
If you do not specify a launch template, then you will be able to configure the above options in the Rancher UI and all of them can be updated after creation. In order to take advantage of all of these options, Rancher will create and manage a launch template for you. Each cluster in Rancher will have one Rancher-managed launch template and each managed node group that does not have a specified launch template will have one version of the managed launch template. The name of this launch template will have the prefix "rancher-managed-lt-" followed by the display name of the cluster. In addition, the Rancher-managed launch template will be tagged with the key "rancher-managed-template" and value "do-not-modify-or-delete" to help identify it as Rancher-managed. It is important that this launch template and its versions not be modified, deleted, or used with any other clusters or managed node groups. Doing so could result in your node groups being "degraded" and needing to be destroyed and recreated.
|
||||
|
||||
#### Custom AMIs
|
||||
|
||||
If you specify a custom AMI, whether in a launch template or in Rancher, then the image must be [configured properly](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/) and you must provide user data to [bootstrap the node](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami). This is considered an advanced use case and understanding the requirements is imperative.
|
||||
|
||||
If you specify a launch template that does not contain a custom AMI, then Amazon will use the [EKS-optimized AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html) for the Kubernetes version and selected region. You can also select a [GPU enabled instance](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html#gpu-ami) for workloads that would benefit from it.
|
||||
|
||||
>**Note**
|
||||
>The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template.
|
||||
|
||||
#### Spot instances
|
||||
|
||||
Spot instances are now [supported by EKS](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-capacity-types-spot). If a launch template is specified, Amazon recommends that the template not provide an instance type. Instead, Amazon recommends providing multiple instance types. If the "Request Spot Instances" checkbox is enabled for a node group, then you will have the opportunity to provide multiple instance types.
|
||||
|
||||
>**Note**
|
||||
>Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration.
|
||||
|
||||
#### Node Group Settings
|
||||
|
||||
The following settings are also configurable. All of these except for the "Node Group Name" are editable after the node group is created.
|
||||
|
||||
| Option | Description |
|
||||
| ------- | ------------ |
|
||||
| Node Group Name | The name of the node group. |
|
||||
| Desired ASG Size | The desired number of instances. |
|
||||
| Maximum ASG Size | The maximum number of instances. This setting won't take effect until the [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) is installed. |
|
||||
| Minimum ASG Size | The minimum number of instances. This setting won't take effect until the [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) is installed. |
|
||||
| Labels | Kubernetes labels applied to the nodes in the managed node group. |
|
||||
| Tags | These are tags for the managed node group and do not propagate to any of the associated resources. |
|
||||
|
||||
|
||||
### Configuring the Refresh Interval
|
||||
|
||||
The `eks-refresh-cron` setting is deprecated. It has been migrated to the `eks-refresh` setting, which is an integer representing seconds.
|
||||
|
||||
The default value is 300 seconds.
|
||||
|
||||
The syncing interval can be changed by running `kubectl edit setting eks-refresh`.
|
||||
|
||||
If the `eks-refresh-cron` setting was previously set, the migration will happen automatically.
|
||||
|
||||
The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs.
|
||||
|
||||
-307
@@ -1,307 +0,0 @@
|
||||
---
|
||||
title: GKE Cluster Configuration Reference
|
||||
shortTitle: GKE Cluster Configuration
|
||||
weight: 3
|
||||
---
|
||||
|
||||
# Changes in Rancher v2.6
|
||||
|
||||
- Support for additional configuration options:
|
||||
- Project network isolation
|
||||
- Network tags
|
||||
|
||||
# Cluster Location
|
||||
|
||||
| Value | Description |
|
||||
|--------|--------------|
|
||||
| Location Type | Zonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to [these docs.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane) |
|
||||
| Zone | Each region in Compute engine contains a number of zones. For more information about available regions and zones, refer to [these docs.](https://cloud.google.com/compute/docs/regions-zones#available) |
|
||||
| Additional Zones | For zonal clusters, you can select additional zones to create a [multi-zone cluster.](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters) |
|
||||
| Region | For [regional clusters,](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters) you can select a region. For more information about available regions and zones, refer to [this section](https://cloud.google.com/compute/docs/regions-zones#available). The first part of each zone name is the name of the region. |
|
||||
|
||||
# Cluster Options
|
||||
|
||||
### Kubernetes Version
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning)
|
||||
|
||||
### Container Address Range
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster.
|
||||
|
||||
### Network
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to [this page](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets).
|
||||
|
||||
### Node Subnet / Subnet
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the **Network** field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, **Subnetwork Name** is required to generate one. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)
|
||||
|
||||
### Subnetwork Name
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Automatically create a subnetwork with the provided name. Required if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. For more information on subnetworks, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)
|
||||
|
||||
### Ip Aliases
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Enable [alias IPs](https://cloud.google.com/vpc/docs/alias-ip). This enables VPC-native traffic routing. Required if using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc).
|
||||
|
||||
### Network Policy
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Enable network policy enforcement on the cluster. A network policy defines the level of communication that can occur between pods and services in the cluster. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy)
|
||||
|
||||
### Project Network Isolation
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
choose whether to enable or disable inter-project communication. Note that enabling Project Network Isolation will automatically enable Network Policy and Network Policy Config, but not vice versa.
|
||||
|
||||
### Node Ipv4 CIDR Block
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The IP address range of the instance IPs in this cluster. Can be set if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. Must be a valid CIDR range, e.g. 10.96.0.0/14. For more information on how to determine the IP address range, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing)
|
||||
|
||||
### Cluster Secondary Range Name
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The name of an existing secondary range for Pod IP addresses. If selected, **Cluster Pod Address Range** will automatically be populated. Required if using a Shared VPC network.
|
||||
|
||||
### Cluster Pod Address Range
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The IP address range assigned to pods in the cluster. Must be a valid CIDR range, e.g. 10.96.0.0/11. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your pods, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_pods)
|
||||
|
||||
### Services Secondary Range Name
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The name of an existing secondary range for service IP addresses. If selected, **Service Address Range** will be automatically populated. Required if using a Shared VPC network.
|
||||
|
||||
### Service Address Range
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The address range assigned to the services in the cluster. Must be a valid CIDR range, e.g. 10.94.0.0/18. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your services, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_svcs)
|
||||
|
||||
### Private Cluster
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/).
|
||||
|
||||
Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP.
|
||||
|
||||
### Enable Private Endpoint
|
||||
|
||||
> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.6/en/cluster-admin/editing-clusters/gke-config-reference/private-clusters/).
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Locks down external access to the control plane endpoint. Only available if **Private Cluster** is also selected. If selected, and if Rancher does not have direct access to the Virtual Private Cloud network the cluster is running in, Rancher will provide a registration command to run on the cluster to enable Rancher to connect to it.
|
||||
|
||||
### Master IPV4 CIDR Block
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The IP range for the control plane VPC.
|
||||
|
||||
### Master Authorized Network
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required.
|
||||
|
||||
# Additional Options
|
||||
|
||||
### Cluster Addons
|
||||
|
||||
Additional Kubernetes cluster components. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster.AddonsConfig)
|
||||
|
||||
#### Horizontal Pod Autoscaling
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler)
|
||||
|
||||
#### HTTP (L7) Load Balancing
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
HTTP (L7) Load Balancing distributes HTTP and HTTPS traffic to backends hosted on GKE. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer)
|
||||
|
||||
#### Network Policy Config (master only)
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Configuration for NetworkPolicy. This only tracks whether the addon is enabled or not on the master, it does not track whether network policy is enabled for the nodes.
|
||||
|
||||
### Cluster Features (Alpha Features)
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters)
|
||||
|
||||
### Logging Service
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
The logging service the cluster uses to write logs. Use either [Cloud Logging](https://cloud.google.com/logging) or no logging service in which case no logs are exported from the cluster.
|
||||
|
||||
### Monitoring Service
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
The monitoring service the cluster uses to write metrics. Use either [Cloud Monitoring](https://cloud.google.com/monitoring) or monitoring service in which case no metrics are exported from the cluster.
|
||||
|
||||
|
||||
### Maintenance Window
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions)
|
||||
|
||||
# Node Pools
|
||||
|
||||
In this section, enter details describing the configuration of each node in the node pool.
|
||||
|
||||
### Kubernetes Version
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
The Kubernetes version for each node in the node pool. For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning)
|
||||
|
||||
### Image Type
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images)
|
||||
|
||||
> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging]({{<baseurl>}}/rancher/v2.0-v2.4/en/cluster-admin/tools/logging) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature]({{<baseurl>}}/rancher/v2.6/en/logging) is compatible with the Container-Optimized OS image.
|
||||
|
||||
> Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool.
|
||||
|
||||
### Machine Type
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
The virtualized hardware resources available to node instances. For more information on Google Cloud machine types, refer to [this page.](https://cloud.google.com/compute/docs/machine-types#machine_types)
|
||||
|
||||
### Root Disk Type
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to [this section.](https://cloud.google.com/compute/docs/disks)
|
||||
|
||||
### Local SSD Disks
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Configure each node's local SSD disk storage in GB. Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see [this section.](https://cloud.google.com/compute/docs/disks#localssds)
|
||||
|
||||
### Preemptible nodes (beta)
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms)
|
||||
|
||||
### Taints
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool.
|
||||
|
||||
### Node Labels
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
You can apply labels to the node pool, which applies the labels to all nodes in the pool.
|
||||
|
||||
Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)
|
||||
|
||||
### Network Tags
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
You can add network tags to the node pool to make firewall rules and routes between subnets. Tags will apply to all nodes in the pool.
|
||||
|
||||
For details on tag syntax and requirements, see the [Kubernetes documentation](https://cloud.google.com/vpc/docs/add-remove-network-tags).
|
||||
|
||||
# Group Details
|
||||
|
||||
In this section, enter details describing the node pool.
|
||||
|
||||
### Name
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Enter a name for the node pool.
|
||||
|
||||
### Initial Node Count
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Integer for the starting number of nodes in the node pool.
|
||||
|
||||
### Max Pod Per Node
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
GKE has a hard limit of 110 Pods per node. For more information on the Kubernetes limits, see [this section.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#dimension_limits)
|
||||
|
||||
### Autoscaling
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
Node pool autoscaling dynamically creates or deletes nodes based on the demands of your workload. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-autoscaler)
|
||||
|
||||
### Auto Repair
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on [auto-repairing nodes.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair)
|
||||
|
||||
### Auto Upgrade
|
||||
|
||||
_Mutable: yes_
|
||||
|
||||
When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is [updated on your behalf.](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades) For more information about auto-upgrading nodes, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades)
|
||||
|
||||
### Access Scopes
|
||||
|
||||
_Mutable: no_
|
||||
|
||||
Access scopes are the legacy method of specifying permissions for your nodes.
|
||||
|
||||
- **Allow default access:** The default access for new clusters is the [Compute Engine default service account.](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account)
|
||||
- **Allow full access to all Cloud APIs:** Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance.
|
||||
- **Set access for each API:** Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call.
|
||||
|
||||
For more information, see the [section about enabling service accounts for a VM.](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)
|
||||
|
||||
|
||||
### Configuring the Refresh Interval
|
||||
|
||||
The refresh interval can be configured through the setting "gke-refresh", which is an integer representing seconds.
|
||||
|
||||
The default value is 300 seconds.
|
||||
|
||||
The syncing interval can be changed by running `kubectl edit setting gke-refresh`.
|
||||
|
||||
The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for GCP APIs.
|
||||
|
||||
-42
@@ -1,42 +0,0 @@
|
||||
---
|
||||
title: Private Clusters
|
||||
weight: 2
|
||||
---
|
||||
|
||||
In GKE, [private clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept) are clusters whose nodes are isolated from inbound and outbound traffic by assigning them internal IP addresses only. Private clusters in GKE have the option of exposing the control plane endpoint as a publicly accessible address or as a private address. This is different from other Kubernetes providers, which may refer to clusters with private control plane endpoints as "private clusters" but still allow traffic to and from nodes. You may want to create a cluster with private nodes, with or without a public control plane endpoint, depending on your organization's networking and security requirements. A GKE cluster provisioned from Rancher can use isolated nodes by selecting "Private Cluster" in the Cluster Options (under "Show advanced options"). The control plane endpoint can optionally be made private by selecting "Enable Private Endpoint".
|
||||
|
||||
### Private Nodes
|
||||
|
||||
Because the nodes in a private cluster only have internal IP addresses, they will not be able to install the cluster agent and Rancher will not be able to fully manage the cluster. This can be overcome in a few ways.
|
||||
|
||||
#### Cloud NAT
|
||||
|
||||
>**Note**
|
||||
>Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing).
|
||||
|
||||
If restricting outgoing internet access is not a concern for your organization, use Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service to allow nodes in the private network to access the internet, enabling them to download the required images from Dockerhub and contact the Rancher management server. This is the simplest solution.
|
||||
|
||||
#### Private registry
|
||||
|
||||
>**Note**
|
||||
>This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient.
|
||||
|
||||
If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image [registry](https://rancher.com/docs/rancher/v2.6/en/installation/other-installation-methods/air-gap/) on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need [direct access](#direct-access) to it.
|
||||
|
||||
### Private Control Plane Endpoint
|
||||
|
||||
If the cluster has a public endpoint exposed, Rancher will be able to reach the cluster, and no additional steps need to be taken. However, if the cluster has no public endpoint, then considerations must be made to ensure Rancher can access the cluster.
|
||||
|
||||
#### Cloud NAT
|
||||
|
||||
>**Note**
|
||||
>Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing).
|
||||
|
||||
As above, if restricting outgoing internet access to the nodes is not a concern, then Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the [kubeconfig](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for the new cluster and run the provided kubectl command on the cluster. Gaining access
|
||||
to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes.
|
||||
|
||||
#### Direct access
|
||||
|
||||
If the Rancher server is run on the same VPC as the cluster's control plane, it will have direct access to the control plane's private endpoint. The cluster nodes will need to have access to a [private registry](#private-registry) to download images as described above.
|
||||
|
||||
You can also use services from Google such as [Cloud VPN](https://cloud.google.com/network-connectivity/docs/vpn/concepts/overview) or [Cloud Interconnect VLAN](https://cloud.google.com/network-connectivity/docs/interconnect) to facilitate connectivity between your organization's network and your Google VPC.
|
||||
-143
@@ -1,143 +0,0 @@
|
||||
---
|
||||
title: K3s Cluster Configuration Reference
|
||||
shortTitle: K3s Cluster Configuration
|
||||
weight: 6
|
||||
---
|
||||
|
||||
This section covers the configuration options that are available in Rancher for a new or existing K3s Kubernetes cluster.
|
||||
|
||||
# Overview
|
||||
|
||||
You can configure the Kubernetes options one of two ways:
|
||||
|
||||
- [Rancher UI](#configuration-options-in-the-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 a K3s config file. Using a config file allows you to set any of the [options](https://rancher.com/docs/k3s/latest/en/installation/install-options/) available in an K3s installation.
|
||||
|
||||
# Configuration Options in the Rancher UI
|
||||
|
||||
> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the K3s cluster configuration file in YAML. For the complete reference of configurable options for K3s clusters in YAML, see the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/install-options/)
|
||||
|
||||
### Basics
|
||||
#### 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).
|
||||
|
||||
For more detail, see [Upgrading Kubernetes]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/upgrading-kubernetes).
|
||||
|
||||
#### Encrypt Secrets
|
||||
|
||||
Option to enable or disable secrets encryption. When enabled, secrets will be encrypted using a AES-CBC key. If disabled, any previously secrets will not be readable until encryption is enabled again. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/advanced/#secrets-encryption-config-experimental) for details.
|
||||
|
||||
#### Project Network Isolation
|
||||
|
||||
If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.
|
||||
|
||||
#### SELinux
|
||||
|
||||
Option to enable or disable [SELinux](https://rancher.com/docs/k3s/latest/en/advanced/#selinux-support) support.
|
||||
|
||||
#### CoreDNS
|
||||
|
||||
By default, [CoreDNS](https://coredns.io/) is installed as the default DNS provider. If CoreDNS is not installed, an alternate DNS provider must be installed yourself. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#coredns) for details..
|
||||
|
||||
#### Klipper Service LB
|
||||
|
||||
Option to enable or disable the [Klipper](https://github.com/rancher/klipper-lb) service load balancer. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#service-load-balancer) for details.
|
||||
|
||||
#### Traefik Ingress
|
||||
|
||||
Option to enable or disable the [Traefik](https://traefik.io/) HTTP reverse proxy and load balancer. For more details and configuration options, see the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#traefik-ingress-controller).
|
||||
|
||||
#### Local Storage
|
||||
|
||||
Option to enable or disable [local storage](https://rancher.com/docs/k3s/latest/en/storage/) on the node(s).
|
||||
|
||||
#### Metrics Server
|
||||
|
||||
Option to enable or disable the [metrics server](https://github.com/kubernetes-incubator/metrics-server). If enabled, ensure port 10250 is opened for inbound TCP traffic.
|
||||
|
||||
### Add-On Config
|
||||
|
||||
Additional Kubernetes manifests, managed as a [Add-on](https://kubernetes.io/docs/concepts/cluster-administration/addons/), to apply to the cluster on startup. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/helm/#automatically-deploying-manifests-and-helm-charts) for details.
|
||||
|
||||
### Agent Environment Vars
|
||||
|
||||
Option to set environment variables for [K3s agents](https://rancher.com/docs/k3s/latest/en/architecture/). The environment variables can be set using key value pairs. Refer to the [K3 documentation](https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config/) for more details.
|
||||
|
||||
### etcd
|
||||
|
||||
#### Automatic Snapshots
|
||||
|
||||
Option to enable or disable recurring etcd snapshots. If enabled, users have the option to configure the frequency of snapshots. For details, refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/backup-restore/#creating-snapshots).
|
||||
|
||||
#### Metrics
|
||||
|
||||
Option to choose whether to expose etcd metrics to the public or only within the cluster.
|
||||
|
||||
### Networking
|
||||
|
||||
#### Cluster CIDR
|
||||
|
||||
IPv4/IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16).
|
||||
|
||||
#### Service CIDR
|
||||
|
||||
IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16).
|
||||
|
||||
#### Cluster DNS
|
||||
|
||||
IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10).
|
||||
|
||||
#### Cluster Domain
|
||||
|
||||
Select the domain for the cluster. The default is `cluster.local`.
|
||||
|
||||
#### NodePort Service 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). The default is `30000-32767`.
|
||||
|
||||
#### TLS Alternate Names
|
||||
|
||||
Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert.
|
||||
|
||||
#### Authorized Cluster Endpoint
|
||||
|
||||
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.
|
||||
|
||||
For more detail on how an authorized cluster endpoint works and why it is used, refer to the [architecture section.]({{<baseurl>}}/rancher/v2.6/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.6/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
### Registries
|
||||
|
||||
Select the image repository to pull Rancher images from. For more details and configuration options, see the [K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/).
|
||||
|
||||
### Upgrade Strategy
|
||||
|
||||
#### Controle Plane Concurrency
|
||||
|
||||
Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.
|
||||
|
||||
#### Worker Concurrency
|
||||
|
||||
Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.
|
||||
|
||||
#### Drain Nodes (Control Plane)
|
||||
|
||||
Option to remove all pods from the node prior to upgrading.
|
||||
|
||||
#### Drain Nodes (Worker Nodes)
|
||||
|
||||
Option to remove all pods from the node prior to upgrading.
|
||||
|
||||
### Advanced
|
||||
|
||||
Option to set kubelet options for different nodes. For available options, refer to the [Kubernetes documentation](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/).
|
||||
|
||||
# Cluster Config File
|
||||
|
||||
Instead of using the Rancher UI forms to choose Kubernetes options for the cluster, advanced users can create an K3s config file. Using a config file allows you to set any of the [options](https://rancher.com/docs/k3s/latest/en/installation/install-options/) available in an K3s installation.
|
||||
|
||||
To edit an K3s config file directly from the Rancher UI, click **Edit as YAML**.
|
||||
|
||||
|
||||
-360
@@ -1,360 +0,0 @@
|
||||
---
|
||||
title: RKE Cluster Configuration Reference
|
||||
shortTitle: RKE Cluster Configuration
|
||||
weight: 1
|
||||
---
|
||||
|
||||
When Rancher installs Kubernetes, it uses [RKE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) or [RKE2](https://docs.rke2.io/) as the Kubernetes distribution.
|
||||
|
||||
This section covers the configuration options that are available in Rancher for a new or existing RKE Kubernetes cluster.
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Editing Clusters with a Form in the Rancher UI](#editing-clusters-with-a-form-in-the-rancher-ui)
|
||||
- [Editing Clusters with YAML](#editing-clusters-with-yaml)
|
||||
- [Configuration Options in the Rancher UI](#configuration-options-in-the-rancher-ui)
|
||||
- [Kubernetes Version](#kubernetes-version)
|
||||
- [Network Provider](#network-provider)
|
||||
- [Project Network Isolation](#project-network-isolation)
|
||||
- [Kubernetes Cloud Providers](#kubernetes-cloud-providers)
|
||||
- [Private Registries](#private-registries)
|
||||
- [Authorized Cluster Endpoint](#authorized-cluster-endpoint)
|
||||
- [Node Pools](#node-pools)
|
||||
- [NGINX Ingress](#nginx-ingress)
|
||||
- [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)
|
||||
- [Default Pod Security Policy](#default-pod-security-policy)
|
||||
- [Node Port Range](#node-port-range)
|
||||
- [Recurring etcd Snapshots](#recurring-etcd-snapshots)
|
||||
- [Agent Environment Variables](#agent-environment-variables)
|
||||
- [Updating ingress-nginx](#updating-ingress-nginx)
|
||||
- [RKE Cluster Config File Reference](#rke-cluster-config-file-reference)
|
||||
- [Config File Structure in Rancher](#config-file-structure-in-rancher)
|
||||
- [Default DNS Provider](#default-dns-provider)
|
||||
- [Rancher Specific Parameters in YAML](#rancher-specific-parameters-in-yaml)
|
||||
- [docker_root_dir](#docker_root_dir)
|
||||
- [enable_cluster_monitoring](#enable_cluster_monitoring)
|
||||
- [enable_network_policy](#enable_network_policy)
|
||||
- [local_cluster_auth_endpoint](#local_cluster_auth_endpoint)
|
||||
- [Custom Network Plug-in](#custom-network-plug-in)
|
||||
|
||||
# Overview
|
||||
|
||||
You can configure the Kubernetes options one of two ways:
|
||||
|
||||
- [Rancher UI](#rancher-ui-options): 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.
|
||||
|
||||
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)
|
||||
|
||||
In [clusters launched by RKE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/), you can edit any of the remaining options that follow.
|
||||
|
||||
For an example of RKE config file syntax, see the [RKE documentation]({{<baseurl>}}/rke/latest/en/example-yamls/).
|
||||
|
||||
The forms in the Rancher UI don't include all advanced options for configuring RKE. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.]({{<baseurl>}}/rke/latest/en/config-options/)
|
||||
|
||||
# Editing Clusters with a Form in the Rancher UI
|
||||
|
||||
To edit your cluster,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. Go to the cluster you want to configure and click **⋮ > Edit Config**.
|
||||
|
||||
|
||||
# Editing Clusters with YAML
|
||||
|
||||
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.
|
||||
|
||||
RKE clusters (also called RKE1 clusters) are edited differently than RKE2 and K3s clusters.
|
||||
|
||||
To edit an RKE config file directly from the Rancher UI,
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the RKE cluster you want to configure. Click and click **⋮ > Edit Config**. This take you to the RKE configuration form. Note: Because cluster provisioning changed in Rancher 2.6, the **⋮ > Edit as YAML** can be used for configuring RKE2 clusters, but it can't be used for editing RKE1 configuration.
|
||||
1. In the configuration form, scroll down and click **Edit as YAML**.
|
||||
1. Edit the RKE options under the `rancher_kubernetes_engine_config` directive.
|
||||
|
||||
# Configuration Options in the Rancher UI
|
||||
|
||||
> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE cluster configuration file in YAML. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.]({{<baseurl>}}/rke/latest/en/config-options/)
|
||||
|
||||
### 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).
|
||||
|
||||
For more detail, see [Upgrading Kubernetes]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/upgrading-kubernetes).
|
||||
|
||||
### 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.6/en/faq/networking/cni-providers/).
|
||||
|
||||
> 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)
|
||||
|
||||
**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.6/en/cluster-provisioning/rke-clusters/options/#cluster-config-file) and the [Weave Network Plug-in Options]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options).
|
||||
|
||||
### Project Network Isolation
|
||||
|
||||
If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.
|
||||
|
||||
Project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.
|
||||
|
||||
### Kubernetes Cloud Providers
|
||||
|
||||
You can configure a [Kubernetes cloud provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers). If you want to use dynamically provisioned [volumes and storage]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/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](#cluster-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.
|
||||
|
||||
### Private Registries
|
||||
|
||||
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.6/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.
|
||||
|
||||
For more information on setting up a private registry for components applied during the provisioning of the cluster, see the [RKE documentation on private registries]({{<baseurl>}}/rke/latest/en/config-options/private-registries/).
|
||||
|
||||
Rancher v2.6 introduced the ability to configure [ECR registries for RKE clusters]({{<baseurl>}}/rke/latest/en/config-options/private-registries/#amazon-elastic-container-registry-ecr-private-registry-setup).
|
||||
|
||||
### Authorized Cluster Endpoint
|
||||
|
||||
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.6/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.6/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.6/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
### Node Pools
|
||||
|
||||
For information on using the Rancher UI to set up node pools in an RKE cluster, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools)
|
||||
|
||||
### 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
|
||||
|
||||
Option to enable or disable [Metrics Server]({{<baseurl>}}/rke/latest/en/config-options/add-ons/metrics-server/).
|
||||
|
||||
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.6/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down.
|
||||
|
||||
You must have an existing Pod Security Policy configured before you can use this option.
|
||||
|
||||
### 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, Rancher will stop pods from running on nodes that don't have a supported Docker version installed.
|
||||
|
||||
For details on which Docker versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)
|
||||
|
||||
### 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`), specify the correct Docker Root Directory in this option.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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`.
|
||||
|
||||
### Recurring etcd Snapshots
|
||||
|
||||
Option to enable or disable [recurring etcd snapshots]({{<baseurl>}}/rke/latest/en/etcd-snapshots/#etcd-recurring-snapshots).
|
||||
|
||||
### Agent Environment Variables
|
||||
|
||||
Option to set environment variables for [rancher agents]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/rancher-agents/). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
# RKE Cluster Config File Reference
|
||||
|
||||
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.
|
||||
|
||||
For the complete reference for configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.]({{<baseurl>}}/rke/latest/en/config-options/)
|
||||
|
||||
### Config File Structure in Rancher
|
||||
|
||||
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.
|
||||
|
||||
<details id="v2.3.0-cluster-config-file">
|
||||
<summary>Example Cluster Config File</summary>
|
||||
|
||||
```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
|
||||
```
|
||||
</details>
|
||||
|
||||
### 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 in YAML
|
||||
|
||||
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.6/en/monitoring-alerting/).
|
||||
|
||||
### enable_network_policy
|
||||
|
||||
Option to enable or disable Project Network Isolation.
|
||||
|
||||
Project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.
|
||||
|
||||
### local_cluster_auth_endpoint
|
||||
|
||||
See [Authorized Cluster Endpoint](#authorized-cluster-endpoint).
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
local_cluster_auth_endpoint:
|
||||
enabled: true
|
||||
fqdn: "FQDN"
|
||||
ca_certs: |-
|
||||
-----BEGIN CERTIFICATE-----
|
||||
...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
### Custom Network Plug-in
|
||||
|
||||
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)
|
||||
-188
@@ -1,188 +0,0 @@
|
||||
---
|
||||
title: RKE2 Cluster Configuration Reference
|
||||
shortTitle: RKE2 Cluster Configuration
|
||||
weight: 5
|
||||
---
|
||||
|
||||
This section covers the configuration options that are available in Rancher for a new or existing RKE2 Kubernetes cluster.
|
||||
|
||||
# Overview
|
||||
|
||||
You can configure the Kubernetes options in one of the two following ways:
|
||||
|
||||
- [Rancher UI](#configuration-options-in-the-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 RKE2 config file. Using a config file allows you to set any of the [options](https://docs.rke2.io/install/install_options/install_options) available in an RKE2 installation.
|
||||
|
||||
# Configuration Options in the Rancher UI
|
||||
|
||||
> Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE2 cluster configuration file in YAML. For the complete reference of configurable options for RKE2 Kubernetes clusters in YAML, see the [RKE2 documentation.](https://docs.rke2.io/install/install_options/install_options/)
|
||||
|
||||
### Basics
|
||||
#### 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).
|
||||
|
||||
For more detail, see [Upgrading Kubernetes]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/upgrading-kubernetes).
|
||||
|
||||
#### Container Network Provider
|
||||
|
||||
The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses.
|
||||
|
||||
> 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 to 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)
|
||||
- [Cilium](https://cilium.io/)*
|
||||
- [Calico](https://docs.projectcalico.org/v3.11/introduction/)
|
||||
- [Multus](https://github.com/k8snetworkplumbingwg/multus-cni)
|
||||
|
||||
\* When using [project network isolation](#project-network-isolation) in the [Cilium CNI]({{<baseurl>}}/rancher/v2.6/en/faq/networking/cni-providers/#cilium), it is possible to enable cross-node ingress routing. Click the [CNI provider docs]({{<baseurl>}}/rancher/v2.6/en/faq/networking/cni-providers/#ingress-routing-across-nodes-in-cilium) to learn more.
|
||||
|
||||
For more details on the different networking providers and how to configure them, please view our [RKE2 documentation](https://docs.rke2.io/install/network_options/).
|
||||
|
||||
##### Dual-stack Networking
|
||||
|
||||
[Dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) networking is supported for all CNI providers. To configure RKE2 in dual-stack mode, set valid IPv4/IPv6 CIDRs for your [Cluster CIDR](#cluster-cidr) and/or [Service CIDR](#service-cidr).
|
||||
|
||||
###### Additional Configuration {#dual-stack-additional-config}
|
||||
|
||||
When using `cilium` or `multus,cilium` as your container network interface provider, ensure the **Enable IPv6 Support** option is also enabled.
|
||||
|
||||
#### Cloud Provider
|
||||
|
||||
You can configure a [Kubernetes cloud provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers). If you want to use dynamically provisioned [volumes and storage]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/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](#cluster-config-file) to configure the cloud provider. Please reference [this documentation]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider.
|
||||
|
||||
#### Default Pod Security Policy
|
||||
|
||||
Choose the default [pod security policy]({{<baseurl>}}/rancher/v2.6/en/admin-settings/pod-security-policies/) for the cluster. Please refer to the [RKE2 documentation](https://docs.rke2.io/security/policies/) on the specifications of each available policy.
|
||||
|
||||
#### Worker CIS Profile
|
||||
|
||||
Select a [CIS benchmark]({{<baseurl>}}/rancher/v2.6/en/cis-scans/) to validate the system configuration against.
|
||||
|
||||
#### Project Network Isolation
|
||||
|
||||
If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.
|
||||
|
||||
Project network isolation is available if you are using any RKE2 network plugin that supports the enforcement of Kubernetes network policies, such as Canal.
|
||||
|
||||
#### SELinux
|
||||
|
||||
Option to enable or disable [SELinux](https://docs.rke2.io/security/selinux) support.
|
||||
|
||||
#### CoreDNS
|
||||
|
||||
By default, [CoreDNS](https://coredns.io/) is installed as the default DNS provider. If CoreDNS is not installed, an alternate DNS provider must be installed yourself. Refer to the [RKE2 documentation](https://docs.rke2.io/networking/#coredns) for additional CoreDNS configurations.
|
||||
|
||||
#### 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. Refer to the [RKE2 documentation](https://docs.rke2.io/networking/#nginx-ingress-controller) for additional configuration options.
|
||||
|
||||
Refer to the [RKE2 documentation](https://docs.rke2.io/networking/#nginx-ingress-controller) for additional configuration options.
|
||||
|
||||
#### Metrics Server
|
||||
|
||||
Option to enable or disable [Metrics Server]({{<baseurl>}}/rke/latest/en/config-options/add-ons/metrics-server/).
|
||||
|
||||
Each cloud provider capable of launching a cluster using RKE2 can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal.
|
||||
|
||||
### Add-On Config
|
||||
|
||||
Additional Kubernetes manifests, managed as an [Add-on](https://kubernetes.io/docs/concepts/cluster-administration/addons/), to apply to the cluster on startup. Refer to the [RKE2 documentation](https://docs.rke2.io/helm/#automatically-deploying-manifests-and-helm-charts) for details.
|
||||
|
||||
### Agent Environment Vars
|
||||
|
||||
Option to set environment variables for [Rancher agents](https://rancher.com/docs/rancher/v2.6/en/cluster-provisioning/rke-clusters/rancher-agents/). The environment variables can be set using key value pairs. Refer to the [RKE2 documentation](https://docs.rke2.io/install/install_options/linux_agent_config/) for more details.
|
||||
|
||||
### etcd
|
||||
|
||||
#### Automatic Snapshots
|
||||
|
||||
Option to enable or disable recurring etcd snapshots. If enabled, users have the option to configure the frequency of snapshots. For details, refer to the [RKE2 documentation](https://docs.rke2.io/backup_restore/#creating-snapshots). Note that with RKE2, snapshots are stored on each etcd node. This varies from RKE1 which only stores one snapshot per cluster.
|
||||
|
||||
#### Metrics
|
||||
|
||||
Option to choose whether to expose etcd metrics to the public or only within the cluster.
|
||||
|
||||
### Networking
|
||||
|
||||
#### Cluster CIDR
|
||||
|
||||
IPv4 and/or IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16).
|
||||
|
||||
##### Dual-stack Networking
|
||||
|
||||
To configure [dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) mode, enter a valid IPv4/IPv6 CIDR. For example `10.42.0.0/16,2001:cafe:42:0::/56`.
|
||||
|
||||
[Additional configuration](#dual-stack-additional-config) is required when using `cilium` or `multus,cilium` as your [container network](#container-network) interface provider.
|
||||
|
||||
#### Service CIDR
|
||||
|
||||
IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16).
|
||||
|
||||
##### Dual-stack Networking
|
||||
|
||||
To configure [dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) mode, enter a valid IPv4/IPv6 CIDR. For example `10.42.0.0/16,2001:cafe:42:0::/56`.
|
||||
|
||||
[Additional configuration](#dual-stack-additional-config) is required when using `cilium ` or `multus,cilium` as your [container network](#container-network) interface provider.
|
||||
|
||||
#### Cluster DNS
|
||||
|
||||
IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10).
|
||||
|
||||
#### Cluster Domain
|
||||
|
||||
Select the domain for the cluster. The default is `cluster.local`.
|
||||
|
||||
#### NodePort Service 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). The default is `30000-32767`.
|
||||
|
||||
#### TLS Alternate Names
|
||||
|
||||
Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert.
|
||||
|
||||
#### Authorized Cluster Endpoint
|
||||
|
||||
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.
|
||||
|
||||
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.6/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.6/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint)
|
||||
|
||||
### Registries
|
||||
|
||||
Select the image repository to pull Rancher images from. For more details and configuration options, see the [RKE2 documentation](https://docs.rke2.io/install/containerd_registry_configuration/).
|
||||
|
||||
### Upgrade Strategy
|
||||
|
||||
#### Control Plane Concurrency
|
||||
|
||||
Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.
|
||||
|
||||
#### Worker Concurrency
|
||||
|
||||
Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.
|
||||
|
||||
#### Drain Nodes (Control Plane)
|
||||
|
||||
Option to remove all pods from the node prior to upgrading.
|
||||
|
||||
#### Drain Nodes (Worker Nodes)
|
||||
|
||||
Option to remove all pods from the node prior to upgrading.
|
||||
|
||||
### Advanced
|
||||
|
||||
Option to set kubelet options for different nodes. For available options, refer to the [Kubernetes documentation](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/).
|
||||
|
||||
# Cluster Config File
|
||||
|
||||
Instead of using the Rancher UI forms to choose Kubernetes options for the cluster, advanced users can create an RKE2 config file. Using a config file allows you to set any of the [options](https://docs.rke2.io/install/install_options/install_options) available in an RKE2 installation.
|
||||
|
||||
To edit an RKE2 config file directly from the Rancher UI, click **Edit as YAML**.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Syncing
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Syncing is the feature for EKS and GKE clusters that causes Rancher to update the clusters' values so they are up to date with their corresponding cluster object in the hosted Kubernetes provider. This enables Rancher to not be the sole owner of a hosted cluster’s state. Its largest limitation is that processing an update from Rancher and another source at the same time or within 5 minutes of one finishing may cause the state from one source to completely overwrite the other.
|
||||
|
||||
### How it works
|
||||
|
||||
There are two fields on the Rancher Cluster object that must be understood to understand how syncing works:
|
||||
|
||||
1. The config object for the cluster, located on the Spec of the Cluster:
|
||||
|
||||
* For EKS, the field is called EKSConfig
|
||||
* For GKE, the field is called GKEConfig
|
||||
|
||||
2. The UpstreamSpec object
|
||||
|
||||
* For EKS, this is located on the EKSStatus field on the Status of the Cluster.
|
||||
* For GKE, this is located on the GKEStatus field on the Status of the Cluster.
|
||||
|
||||
The struct types that define these objects can be found in their corresponding operator projects:
|
||||
|
||||
* [eks-operator](https://github.com/rancher/eks-operator/blob/master/pkg/apis/eks.cattle.io/v1/types.go)
|
||||
* [gke-operator](https://github.com/rancher/gke-operator/blob/master/pkg/apis/gke.cattle.io/v1/types.go)
|
||||
|
||||
All fields with the exception of the cluster name, the location (region or zone), Imported, and the cloud credential reference, are nillable on this Spec object.
|
||||
|
||||
The EKSConfig or GKEConfig represents desired state for its non-nil values. Fields that are non-nil in the config object can be thought of as “managed". When a cluster is created in Rancher, all fields are non-nil and therefore “managed”. When a pre-existing cluster is registered in rancher all nillable fields are nil and are not “managed”. Those fields become managed once their value has been changed by Rancher.
|
||||
|
||||
UpstreamSpec represents the cluster as it is in the hosted Kubernetes provider and is refreshed on an interval of 5 minutes. After the UpstreamSpec has been refreshed, Rancher checks if the cluster has an update in progress. If it is updating, nothing further is done. If it is not currently updating, any “managed” fields on EKSConfig or GKEConfig are overwritten with their corresponding value from the recently updated UpstreamSpec.
|
||||
|
||||
The effective desired state can be thought of as the UpstreamSpec + all non-nil fields in the EKSConfig or GKEConfig. This is what is displayed in the UI.
|
||||
|
||||
If Rancher and another source attempt to update a cluster at the same time or within the 5 minute refresh window of an update finishing, then it is likely any “managed” fields can be caught in a race condition. To use EKS as an example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console, then finishes at 11:01, and then tags are updated from Rancher before 11:05 the value will likely be overwritten. This would also occur if tags were updated while the cluster was processing the update. If the cluster was registered and the PrivateAccess fields was nil then this issue should not occur in the aforementioned case.
|
||||
@@ -1,188 +0,0 @@
|
||||
---
|
||||
title: Nodes and Node Pools
|
||||
weight: 2030
|
||||
---
|
||||
|
||||
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.6/en/cluster-provisioning/) 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.6/en/cluster-admin/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)
|
||||
- [Registered nodes](#registered-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 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] | [Registered EKS Nodes][4] | [All Other Registered Nodes][5] | 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 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.6/en/cluster-provisioning/rke-clusters/node-pools/
|
||||
[2]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/custom-nodes/
|
||||
[3]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/
|
||||
[4]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/
|
||||
[5]: {{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/
|
||||
|
||||
\* Delete option accessible via View API
|
||||
|
||||
|
||||
### 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.6/en/cluster-provisioning/rke-clusters/node-pools/)
|
||||
|
||||
Clusters provisioned using [one of the node pool options]({{<baseurl>}}/rancher/v2.6/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.6/en/cluster-provisioning/rke-clusters/node-pools/#about-node-auto-replace) This scale determines the number of active nodes that Rancher maintains for the cluster.
|
||||
|
||||
Rancher uses [node templates]({{<baseurl>}}/rancher/v2.6/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.6/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.
|
||||
|
||||
### Registered Nodes
|
||||
|
||||
Although you can deploy workloads to a [registered cluster]({{< baseurl >}}/rancher/v2.6/en/cluster-provisioning/registered-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 **⋮** icon (**..**.).
|
||||
|
||||
# Viewing a Node in the Rancher API
|
||||
|
||||
Select this option to view the node's [API endpoints]({{< baseurl >}}/rancher/v2.6/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.6/en/cluster-provisioning/rke-clusters/node-pools/#about-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.6/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.6/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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster.
|
||||
1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH will be 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
|
||||
|
||||
When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled.
|
||||
|
||||
- **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.
|
||||
### 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 before 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
|
||||
|
||||
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 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 in the Rancher API under `v3/settings/ignore-node-name`.
|
||||
-19
@@ -1,19 +0,0 @@
|
||||
---
|
||||
title: Assigning Pod Security Policies
|
||||
weight: 2260
|
||||
---
|
||||
|
||||
_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.6/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.
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Adding a Pod Security Policy
|
||||
weight: 80
|
||||
---
|
||||
|
||||
> **Prerequisite:** The options below are available only for clusters that are [launched using RKE.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/)
|
||||
|
||||
When your cluster is running pods with security-sensitive configurations, assign it a [pod security policy]({{<baseurl>}}/rancher/v2.6/en/admin-settings/pod-security-policies/), which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running.
|
||||
|
||||
You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster to which you want to apply a pod security policy and click **⋮ > Edit Config**.
|
||||
1. From **Pod Security Policy Support**, select **Enabled**.
|
||||
|
||||
>**Note:** This option is only available for clusters [provisioned by RKE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/).
|
||||
|
||||
4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster.
|
||||
|
||||
Rancher ships with [policies]({{<baseurl>}}/rancher/v2.6/en/admin-settings/pod-security-policies/#default-pod-security-policies) of `restricted` and `unrestricted`, although you can [create custom policies]({{<baseurl>}}/rancher/v2.6/en/admin-settings/pod-security-policies/#default-pod-security-policies) as well.
|
||||
|
||||
5. Click **Save**.
|
||||
|
||||
**Result:** The pod security policy is applied to the cluster and any projects within the cluster.
|
||||
|
||||
>**Note:** Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run.
|
||||
>
|
||||
>To check if a running workload passes your pod security policy, clone or upgrade it.
|
||||
-183
@@ -1,183 +0,0 @@
|
||||
---
|
||||
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: 2032
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
>**Note:** As of Rancher v2.6, projects are de-emphasized on the UI because it is no longer required to create any Kubernetes resources within a project scope. However, resources such as [Secrets]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/secrets/#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
|
||||
|
||||
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.6/en/k8s-in-rancher/workloads/)
|
||||
- [Load Balancers/Ingress]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/load-balancers-and-ingress/)
|
||||
- [Service Discovery Records]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/service-discovery/)
|
||||
- [Persistent Volume Claims]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/)
|
||||
- [Certificates]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/certificates/)
|
||||
- [ConfigMaps]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/configmaps/)
|
||||
- [Registries]({{<baseurl>}}/rancher/v2.6/en/k8s-in-rancher/registries/)
|
||||
- [Secrets]({{<baseurl>}}/rancher/v2.6/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.6/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.6/en/project-admin/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.6/en/admin-settings/rbac/cluster-project-roles)).
|
||||
- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{<baseurl>}}/rancher/v2.6/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
|
||||
|
||||
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 cluster view and click **Cluster > Projects/Namespaces**. This view shows all of the namespaces in the `system` project.
|
||||
|
||||
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 RKE clusters where 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 in addition to the cluster level. 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. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster you want to project in and click **Explore**.
|
||||
1. Click **Cluster > Projects/Namespaces**.
|
||||
1. Click **Create 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.6/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.
|
||||
>
|
||||
>- By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces.
|
||||
>
|
||||
>- Choose `Custom` to create a custom role on the fly: [Custom Project Roles]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles).
|
||||
|
||||
To add members:
|
||||
|
||||
1. In the **Members** tab, click **Add**.
|
||||
1. From the **Select Member** field, 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. In the **Project Permissions** section, choose a role. For more information, refer to the [documentation on project roles.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/)
|
||||
|
||||
### 4. Optional: Add Resource Quotas
|
||||
|
||||
Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/).
|
||||
|
||||
To add a resource quota,
|
||||
|
||||
1. In the **Resource Quotas** tab, click **Add Resource**.
|
||||
1. Select a **Resource Type**. For more information, see [Resource Quotas.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/projects-and-namespaces/).
|
||||
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.6/en/project-admin/resource-quotas/)
|
||||
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. |
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
title: Restoring a Cluster from Backup
|
||||
weight: 2050
|
||||
---
|
||||
|
||||
etcd backup and recovery for [Rancher launched Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/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.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots), but [one-time snapshots]({{<baseurl>}}/rancher/v2.6/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).
|
||||
|
||||
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 upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster.
|
||||
1. Click the **Snapshots** tab. The listed 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.
|
||||
|
||||
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 restore is similar to restoring to snapshots in Rancher before 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.6/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.6/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots)
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster.
|
||||
1. Click the **Snapshots** tab to view the list of saved snapshots.
|
||||
1. Go to the snapshot you want to restore and click **⋮ > Restore Snapshot**.
|
||||
1. Click **Restore**.
|
||||
|
||||
**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.
|
||||
|
||||
## 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. The cluster should have three etcd nodes to prevent a loss of quorum. 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.6/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.6/en/cluster-admin/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 before v2.2.0, after upgrading Rancher, you must [edit the cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/editing-clusters/) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before 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.6/en/cluster-admin/restoring-etcd/).
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Tools for Logging, Monitoring, and Visibility
|
||||
weight: 2033
|
||||
---
|
||||
|
||||
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 -->
|
||||
|
||||
- [Logging](#logging)
|
||||
- [Monitoring and Alerts](#monitoring-and-alerts)
|
||||
- [Istio](#istio)
|
||||
- [OPA Gatekeeper](#opa-gatekeeper)
|
||||
- [CIS Scans](#cis-scans)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
|
||||
# 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 more information, refer to the logging documentation [here.]({{<baseurl>}}/rancher/v2.6/en/logging/)
|
||||
# Monitoring and Alerts
|
||||
|
||||
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.
|
||||
|
||||
After monitoring is enabled, you can set up alerts and notifiers that provide the mechanism to receive them.
|
||||
|
||||
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 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.
|
||||
|
||||
For more information, refer to the monitoring documentation [here.]({{<baseurl>}}/rancher/v2.6/en/monitoring-alerting/)
|
||||
|
||||
# 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.
|
||||
|
||||
Rancher's integration with Istio was improved in Rancher v2.5.
|
||||
|
||||
For more information, refer to the Istio documentation [here.]({{<baseurl>}}/rancher/v2.6/en/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.6/en/opa-gatekeper)
|
||||
|
||||
# CIS Scans
|
||||
|
||||
Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.
|
||||
|
||||
For more information, refer to the CIS scan documentation [here.]({{<baseurl>}}/rancher/v2.6/en/cis-scans)
|
||||
-134
@@ -1,134 +0,0 @@
|
||||
---
|
||||
title: Upgrading and Rolling Back Kubernetes
|
||||
weight: 70
|
||||
---
|
||||
|
||||
Following an upgrade to the latest version of Rancher, downstream Kubernetes clusters can be upgraded to use the latest supported version of Kubernetes.
|
||||
|
||||
Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the [RKE documentation]({{<baseurl>}}/rke/latest/en/).
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [New Features](#new-features)
|
||||
- [Tested Kubernetes Versions](#tested-kubernetes-versions)
|
||||
- [How Upgrades Work](#how-upgrades-work)
|
||||
- [Recommended Best Practice for Upgrades](#recommended-best-practice-for-upgrades)
|
||||
- [Upgrading the Kubernetes Version](#upgrading-the-kubernetes-version)
|
||||
- [Rolling Back](#rolling-back)
|
||||
- [Configuring the Upgrade Strategy](#configuring-the-upgrade-strategy)
|
||||
- [Configuring the Maximum Unavailable Worker Nodes in the Rancher UI](#configuring-the-maximum-unavailable-worker-nodes-in-the-rancher-ui)
|
||||
- [Enabling Draining Nodes During Upgrades from the Rancher UI](#enabling-draining-nodes-during-upgrades-from-the-rancher-ui)
|
||||
- [Maintaining Availability for Applications During Upgrades](#maintaining-availability-for-applications-during-upgrades)
|
||||
- [Configuring the Upgrade Strategy in the cluster.yml](#configuring-the-upgrade-strategy-in-the-cluster-yml)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
# Tested Kubernetes Versions
|
||||
|
||||
Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.6.0/)
|
||||
|
||||
# How Upgrades Work
|
||||
|
||||
RKE v1.1.0 changed the way that clusters are upgraded.
|
||||
|
||||
In this section of the [RKE documentation,]({{<baseurl>}}/rke/latest/en/upgrades/how-upgrades-work) you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster.
|
||||
|
||||
|
||||
# Recommended Best Practice for Upgrades
|
||||
|
||||
When upgrading the Kubernetes version of a cluster, we recommend that you:
|
||||
|
||||
1. Take a snapshot.
|
||||
1. Initiate a Kubernetes upgrade.
|
||||
1. If the upgrade fails, revert the cluster to the pre-upgrade Kubernetes version. This is achieved by selecting the **Restore etcd and Kubernetes version** option. This will return your cluster to the pre-upgrade kubernetes version before restoring the etcd snapshot.
|
||||
|
||||
The restore operation will work on a cluster that is not in a healthy or active state.
|
||||
|
||||
# Upgrading the Kubernetes Version
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - The options below are available only for [Rancher-launched RKE Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) and [Registered K3s Kubernetes clusters.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-k3s-clusters)
|
||||
> - Before upgrading Kubernetes, [back up your cluster.]({{<baseurl>}}/rancher/v2.6/en/backups)
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**.
|
||||
1. From the **Kubernetes Version** drop-down, choose the version of Kubernetes that you want to use for the cluster.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** Kubernetes begins upgrading for the cluster.
|
||||
|
||||
# Rolling Back
|
||||
|
||||
A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections:
|
||||
|
||||
- [Backing up a cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/backing-up-etcd/#how-snapshots-work)
|
||||
- [Restoring a cluster from backup]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/restoring-etcd/#restoring-a-cluster-from-a-snapshot)
|
||||
|
||||
# Configuring the Upgrade Strategy
|
||||
|
||||
As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain [conditions and requirements]({{<baseurl>}}/rke/latest/en/upgrades/maintaining-availability) are met.
|
||||
|
||||
The upgrade strategy can be configured in the Rancher UI, or by editing the `cluster.yml`. More advanced options are available by editing the `cluster.yml`.
|
||||
|
||||
### Configuring the Maximum Unavailable Worker Nodes in the Rancher UI
|
||||
|
||||
From the Rancher UI, the maximum number of unavailable worker nodes can be configured. During a cluster upgrade, worker nodes will be upgraded in batches of this size.
|
||||
|
||||
By default, the maximum number of unavailable worker is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node.
|
||||
|
||||
To change the default number or percentage of worker nodes,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**.
|
||||
1. In the **Upgrade Strategy** tab, enter the **Worker Concurrency** as a fixed number or percentage. To get this number, you can take the number of nodes in your cluster and subtract the max unavailable nodes.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The cluster is updated to use the new upgrade strategy.
|
||||
|
||||
### Enabling Draining Nodes During Upgrades from the Rancher UI
|
||||
|
||||
By default, RKE [cordons](https://kubernetes.io/docs/concepts/architecture/nodes/#manual-node-administration) each node before upgrading it. [Draining](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) is disabled during upgrades by default. If draining is enabled in the cluster configuration, RKE will both cordon and drain the node before it is upgraded.
|
||||
|
||||
To enable draining each node during a cluster upgrade,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster you want to enable node draining and click **⋮ > Edit Config**.
|
||||
1. Click **⋮ > Edit**.
|
||||
1. In the **Upgrade Strategy** tab, go to the **Drain nodes** field and click **Yes**. Node draining is configured separately for control plane and worker nodes.
|
||||
1. Configure the options for how pods are deleted. For more information about each option, refer to [this section.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/nodes/#aggressive-and-safe-draining-options)
|
||||
1. Optionally, configure a grace period. The grace period is the timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. Pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If this value is negative, the default value specified in the pod will be used.
|
||||
1. Optionally, configure a timeout, which is the amount of time the drain should continue to wait before giving up.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The cluster is updated to use the new upgrade strategy.
|
||||
|
||||
> **Note:** As of Rancher v2.4.0, there is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.
|
||||
|
||||
### Maintaining Availability for Applications During Upgrades
|
||||
|
||||
_Available as of RKE v1.1.0_
|
||||
|
||||
In [this section of the RKE documentation,]({{<baseurl>}}/rke/latest/en/upgrades/maintaining-availability/) you'll learn the requirements to prevent downtime for your applications when upgrading the cluster.
|
||||
|
||||
### Configuring the Upgrade Strategy in the cluster.yml
|
||||
|
||||
More advanced upgrade strategy configuration options are available by editing the `cluster.yml`.
|
||||
|
||||
For details, refer to [Configuring the Upgrade Strategy]({{<baseurl>}}/rke/latest/en/upgrades/configuring-strategy) in the RKE documentation. The section also includes an example `cluster.yml` for configuring the upgrade strategy.
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
If a node doesn't come up after an upgrade, the `rke up` command errors out.
|
||||
|
||||
No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum.
|
||||
|
||||
If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue.
|
||||
|
||||
A failed node could be in many different states:
|
||||
|
||||
- Powered off
|
||||
- Unavailable
|
||||
- User drains a node while upgrade is in process, so there are no kubelets on the node
|
||||
- The upgrade itself failed
|
||||
|
||||
If the max unavailable number of nodes is reached during an upgrade, Rancher user clusters will be stuck in updating state and not move forward with upgrading any other control plane nodes. It will continue to evaluate the set of unavailable nodes in case one of the nodes becomes available. If the node cannot be fixed, you must remove the node in order to continue the upgrade.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user