mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-29 22:49:17 +00:00
Apply Divio and update links
This commit is contained in:
Billy Tat
+199
@@ -0,0 +1,199 @@
|
||||
---
|
||||
title: Configuring Active Directory (AD)
|
||||
weight: 1112
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/authentication/active-directory/
|
||||
---
|
||||
|
||||
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](../../../../../pages-for-subheaders/configure-openldap.md) integration.
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users](../../../../../pages-for-subheaders/about-authentication.md#external-authentication-configuration-and-principal-users).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.
|
||||
|
||||
Usually a (non-admin) **Domain User** account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.
|
||||
|
||||
Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.
|
||||
|
||||
> **Using TLS?**
|
||||
>
|
||||
> If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
|
||||
|
||||
## Configuration Steps
|
||||
### Open Active Directory Configuration
|
||||
|
||||
1. Log into the Rancher UI using the initial local `admin` account.
|
||||
2. From the **Global** view, navigate to **Security** > **Authentication**
|
||||
3. Select **Active Directory**. The **Configure an AD server** form will be displayed.
|
||||
|
||||
### Configure Active Directory Server Settings
|
||||
|
||||
In the section titled `1. Configure an Active Directory server`, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch).
|
||||
|
||||
**Table 1: AD Server parameters**
|
||||
|
||||
| Parameter | Description |
|
||||
|:--|:--|
|
||||
| Hostname | Specify the hostname or IP address of the AD server |
|
||||
| Port | Specify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
|
||||
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS).|
|
||||
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the AD server unreachable. |
|
||||
| Service Account Username | Enter the username of an AD account with read-only access to your domain partition (see [Prerequisites](#prerequisites)). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com"). |
|
||||
| Service Account Password | The password for the service account. |
|
||||
| Default Login Domain | When you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field **must** be left empty. |
|
||||
| User Search Base | The Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
|
||||
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".|
|
||||
|
||||
---
|
||||
|
||||
### Configure User/Group Schema
|
||||
|
||||
In the section titled `2. Customize Schema` you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.
|
||||
|
||||
Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values.
|
||||
|
||||
#### User Schema
|
||||
|
||||
The table below details the parameters for the user schema section configuration.
|
||||
|
||||
**Table 2: User schema configuration parameters**
|
||||
|
||||
| Parameter | Description |
|
||||
|:--|:--|
|
||||
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
|
||||
| Username Attribute | The user attribute whose value is suitable as a display name. |
|
||||
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. |
|
||||
| User Member Attribute | The attribute containing the groups that a user is a member of. |
|
||||
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. |
|
||||
| Search Filter | This filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be <code>(|(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 organisation makes use of these nested memberships (ie. you have groups that contain other groups as members. We advise avoiding nested groups when possible). |
|
||||
|
||||
---
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
|
||||
Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`.
|
||||
|
||||
Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, ie. `OU=Groups,DC=acme,DC=com`.
|
||||
|
||||
### Identify User Schema
|
||||
|
||||
The output of the above `ldapsearch` query also allows to determine the correct values to use in the user schema configuration:
|
||||
|
||||
- `Object Class`: **person** [1]
|
||||
- `Username Attribute`: **name** [2]
|
||||
- `Login Attribute`: **sAMAccountName** [3]
|
||||
- `User Member Attribute`: **memberOf** [4]
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead.
|
||||
|
||||
We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.
|
||||
|
||||
### Identify Group Schema
|
||||
|
||||
Next, we'll query one of the groups associated with this user, in this case `CN=examplegroup,OU=Groups,DC=acme,DC=com`:
|
||||
|
||||
```
|
||||
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
|
||||
-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
|
||||
-s sub "CN=examplegroup"
|
||||
```
|
||||
|
||||
This command will inform us on the attributes used for group objects:
|
||||
|
||||
|
||||
|
||||
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](../../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation.
|
||||
+209
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: Configuring Azure AD
|
||||
weight: 1115
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/authentication/azure-ad/
|
||||
---
|
||||
|
||||
_Available as of v2.0.3_
|
||||
|
||||
If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.
|
||||
|
||||
>**Note:** Azure AD integration only supports Service Provider initiated logins.
|
||||
|
||||
>**Prerequisite:** Have an instance of Azure AD configured.
|
||||
|
||||
>**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
|
||||
|
||||
## Azure Active Directory Configuration Outline
|
||||
|
||||
Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.
|
||||
|
||||
<a id="tip"></a>
|
||||
|
||||
>**Tip:** Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
- [1. Register Rancher with Azure](#1-register-rancher-with-azure)
|
||||
- [2. Create 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. From the **Global** view, select **Security > Authentication**.
|
||||
|
||||
1. Select **Azure AD**.
|
||||
|
||||
1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data).
|
||||
|
||||
>**Important:** When entering your Graph Endpoint, remove the tenant ID from the URL, like below.
|
||||
>
|
||||
><code>http<span>s://g</span>raph.windows.net/<del>abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
|
||||
|
||||
The following table maps the values you copied in the Azure portal to the fields in Rancher.
|
||||
|
||||
| Rancher Field | Azure Value |
|
||||
| ------------------ | ------------------------------------- |
|
||||
| Tenant ID | Directory ID |
|
||||
| Application ID | Application ID |
|
||||
| Application Secret | Key Value |
|
||||
| Endpoint | https://login.microsoftonline.com/ |
|
||||
| Graph Endpoint | Microsoft Azure AD Graph API Endpoint |
|
||||
| Token Endpoint | OAuth 2.0 Token Endpoint |
|
||||
| Auth Endpoint | OAuth 2.0 Authorization Endpoint |
|
||||
|
||||
1. Click **Authenticate with Azure**.
|
||||
|
||||
**Result:** Azure Active Directory authentication is configured.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Configuring FreeIPA
|
||||
weight: 1114
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/authentication/freeipa/
|
||||
---
|
||||
|
||||
_Available as of v2.0.5_
|
||||
|
||||
If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- You must have a [FreeIPA Server](https://www.freeipa.org/) configured.
|
||||
>- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key.
|
||||
>- Read [External Authentication Configuration and Principal Users](../../../../../pages-for-subheaders/about-authentication.md#external-authentication-configuration-and-principal-users).
|
||||
|
||||
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
|
||||
|
||||
2. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
3. Select **FreeIPA**.
|
||||
|
||||
4. Complete the **Configure an FreeIPA server** form.
|
||||
|
||||
You may need to log in to your domain controller to find the information requested in the form.
|
||||
|
||||
>**Using TLS?**
|
||||
>If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.
|
||||
<br/>
|
||||
<br/>
|
||||
>**User Search Base vs. Group Search Base**
|
||||
>
|
||||
>Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.
|
||||
>
|
||||
>* If your users and groups are in the same search base, complete only the User Search Base.
|
||||
>* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
|
||||
|
||||
5. If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step.
|
||||
|
||||
>**Search Attribute** The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
|
||||
>
|
||||
>The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields.
|
||||
>
|
||||
> * `uid`: User ID
|
||||
> * `sn`: Last Name
|
||||
> * `givenName`: First Name
|
||||
>
|
||||
> With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field.
|
||||
|
||||
6. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication.
|
||||
|
||||
**Result:**
|
||||
|
||||
- FreeIPA authentication is configured.
|
||||
- You are signed into Rancher with your FreeIPA account (i.e., the _external principal_).
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Configuring GitHub
|
||||
weight: 1116
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/authentication/github/
|
||||
---
|
||||
|
||||
In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.
|
||||
|
||||
>**Prerequisites:** Read [External Authentication Configuration and Principal Users](../../../../../pages-for-subheaders/about-authentication.md#external-authentication-configuration-and-principal-users).
|
||||
|
||||
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
|
||||
|
||||
2. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
3. Select **GitHub**.
|
||||
|
||||
4. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration.
|
||||
|
||||
>**What's an Authorization Callback URL?**
|
||||
>
|
||||
>The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).
|
||||
|
||||
>When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.
|
||||
|
||||
5. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher.
|
||||
|
||||
>**Where do I find the Client ID and Client Secret?**
|
||||
>
|
||||
>From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.
|
||||
|
||||
6. Click **Authenticate with GitHub**.
|
||||
|
||||
7. Use the **Site Access** options to configure the scope of user authorization.
|
||||
|
||||
- **Allow any valid Users**
|
||||
|
||||
_Any_ GitHub user can access Rancher. We generally discourage use of this setting!
|
||||
|
||||
- **Allow members of Clusters, Projects, plus Authorized Users and Organizations**
|
||||
|
||||
Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher.
|
||||
|
||||
- **Restrict access to only Authorized Users and Organizations**
|
||||
|
||||
Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.
|
||||
<br/>
|
||||
8. Click **Save**.
|
||||
|
||||
**Result:**
|
||||
|
||||
- GitHub authentication is configured.
|
||||
- You are signed into Rancher with your GitHub account (i.e., the _external principal_).
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Configuring Google OAuth
|
||||
---
|
||||
_Available as of v2.3.0_
|
||||
|
||||
If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials.
|
||||
|
||||
Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher.
|
||||
|
||||
Within Rancher, only administrators or users with the **Manage Authentication** [global role](../../manage-role-based-access-control-rbac/global-permissions.md) 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 [**Manage OAuth Client Access** page.](https://admin.google.com/AdminHome?chromeless=1#OGX:ManageOauthClients)
|
||||
1. Add the Unique ID obtained in the previous step in the **Client Name** field.
|
||||
1. In the **One or More API Scopes** field, add the following scopes:
|
||||
```
|
||||
openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly
|
||||
```
|
||||
1. Click **Authorize.**
|
||||
|
||||
**Result:** The service account is registered as an OAuth client in your G Suite account.
|
||||
|
||||
# Configuring Google OAuth in Rancher
|
||||
1. Sign into Rancher using a local user assigned the [administrator](../../manage-role-based-access-control-rbac/global-permissions.md) role. This user is also called the local principal.
|
||||
1. From the **Global** view, click **Security > Authentication** from the main menu.
|
||||
1. Click **Google.** The instructions in the UI cover the steps to set up authentication with Google OAuth.
|
||||
1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
|
||||
1. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
|
||||
1. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
|
||||
- **Step One** is about adding Rancher as an authorized domain, which we already covered in [this section.](#1-adding-rancher-as-an-authorized-domain)
|
||||
- For **Step Two,** provide the OAuth credentials JSON that you downloaded after completing [this section.](#2-creating-oauth2-credentials-for-the-rancher-server) You can upload the file or paste the contents into the **OAuth Credentials** field.
|
||||
- For **Step Three,** provide the service account credentials JSON that downloaded at the end of [this section.](#3-creating-service-account-credentials) The credentials will only work if you successfully [registered the service account key](#4-register-the-service-account-key-as-an-oauth-client) as an OAuth client in your G Suite account.
|
||||
1. Click **Authenticate with Google**.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** Google authentication is successfully configured.
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
_Available as of v2.1.0_
|
||||
|
||||
If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
|
||||
- In Keycloak, create a [new SAML client](https://www.keycloak.org/docs/latest/server_admin/#saml-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-clients) for help.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Sign Documents` | `ON` <sup>1</sup>
|
||||
`Sign Assertions` | `ON` <sup>1</sup>
|
||||
All other `ON/OFF` Settings | `OFF`
|
||||
`Client ID` | 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.
|
||||
|
||||
|
||||
|
||||
- In the new SAML client, create Mappers to expose the users fields
|
||||
- Add all "Builtin Protocol Mappers"
|
||||
|
||||
- Create a new "Group list" mapper to map the member attribute to a user's groups
|
||||
|
||||
- Export a `metadata.xml` file from your Keycloak client:
|
||||
From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file.
|
||||
|
||||
>**Note**
|
||||
> Keycloak versions 6.0.0 and up no longer provide the IDP metadata under the `Installation` tab.
|
||||
> You can still get the XML from the following url:
|
||||
>
|
||||
> `https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}/protocol/saml/descriptor`
|
||||
>
|
||||
> The XML obtained from this URL contains `EntitiesDescriptor` as the root element. Rancher expects the root element to be `EntityDescriptor` rather than `EntitiesDescriptor`. So before passing this XML to Rancher, follow these steps to adjust it:
|
||||
>
|
||||
> * Copy all the attributes from `EntitiesDescriptor` to the `EntityDescriptor` that are not present.
|
||||
> * Remove the `<EntitiesDescriptor>` tag from the beginning.
|
||||
> * Remove the `</EntitiesDescriptor>` from the end of the xml.
|
||||
>
|
||||
> You are left with something similar as the example below:
|
||||
>
|
||||
> ```
|
||||
> <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
|
||||
> ....
|
||||
> </EntityDescriptor>
|
||||
> ```
|
||||
|
||||
## Configuring Keycloak in Rancher
|
||||
|
||||
|
||||
1. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
1. Select **Keycloak**.
|
||||
|
||||
1. Complete the **Configure Keycloak Account** form.
|
||||
|
||||
|
||||
| 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
|
||||
|
||||
|
||||
1. After you complete the **Configure Keycloak Account** form, click **Authenticate with Keycloak**, which is at the bottom of the page.
|
||||
|
||||
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.
|
||||
|
||||
>**Note:** You may have to disable your popup blocker to see the IdP login page.
|
||||
|
||||
**Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.
|
||||
|
||||
{{< saml_caveats >}}
|
||||
|
||||
## Annex: Troubleshooting
|
||||
|
||||
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation.
|
||||
|
||||
### You are not redirected to Keycloak
|
||||
|
||||
When you click on **Authenticate with Keycloak**, your are not redirected to your IdP.
|
||||
|
||||
* Verify your Keycloak client configuration.
|
||||
* Make sure `Force Post Binding` set to `OFF`.
|
||||
|
||||
|
||||
### Forbidden message displayed after IdP login
|
||||
|
||||
You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a `Forbidden` message afterwards.
|
||||
|
||||
* Check the Rancher debug log.
|
||||
* If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client.
|
||||
|
||||
### HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata
|
||||
|
||||
This is usually due to the metadata not being created until a SAML provider is configured.
|
||||
Try configuring and saving keycloak as your SAML provider and then accessing the metadata.
|
||||
|
||||
### Keycloak Error: "We're sorry, failed to process response"
|
||||
|
||||
* Check your Keycloak log.
|
||||
* If the log displays `failed: org.keycloak.common.VerificationException: Client does not have a public key`, set `Encrypt Assertions` to `OFF` in your Keycloak client.
|
||||
|
||||
### Keycloak Error: "We're sorry, invalid requester"
|
||||
|
||||
* Check your Keycloak log.
|
||||
* If the log displays `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`, set `Client Signature Required` to `OFF` in your Keycloak client.
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Configuring Okta (SAML)
|
||||
weight: 1210
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
|
||||
|
||||
>**Note:** Okta integration only supports Service Provider initiated logins.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs`
|
||||
`Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata`
|
||||
|
||||
## Configuring Okta in Rancher
|
||||
|
||||
1. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
1. Select **Okta**.
|
||||
|
||||
1. Complete the **Configure Okta Account** form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.
|
||||
|
||||
| Field | Description |
|
||||
| ------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Display Name Field | The attribute name from an attribute statement that contains the display name of users. |
|
||||
| User Name Field | The attribute name from an attribute statement that contains the user name/given name. |
|
||||
| UID Field | The attribute name from an attribute statement that is unique to every user. |
|
||||
| Groups Field | The attribute name in a group attribute statement that exposes your groups. |
|
||||
| Rancher API Host | The URL for your Rancher Server. |
|
||||
| Private Key / Certificate | A key/certificate pair used for Assertion Encryption. |
|
||||
| Metadata XML | The `Identity Provider metadata` file that you find in the application `Sign On` section. |
|
||||
|
||||
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
|
||||
>
|
||||
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt
|
||||
|
||||
|
||||
|
||||
1. After you complete the **Configure Okta Account** form, click **Authenticate with Okta**, which is at the bottom of the page.
|
||||
|
||||
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.
|
||||
|
||||
>**Note:** If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.
|
||||
|
||||
**Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.
|
||||
|
||||
{{< saml_caveats >}}
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Configuring PingIdentity (SAML)
|
||||
weight: 1200
|
||||
---
|
||||
_Available as of v2.0.7_
|
||||
|
||||
If your organization uses Ping Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- You must have a [Ping IdP Server](https://www.pingidentity.com/) configured.
|
||||
>- Following are the Rancher Service Provider URLs needed for configuration:
|
||||
Metadata URL: `https://<rancher-server>/v1-saml/ping/saml/metadata`
|
||||
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/ping/saml/acs`
|
||||
Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
|
||||
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [PingIdentity documentation](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html).
|
||||
|
||||
1. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
1. Select **PingIdentity**.
|
||||
|
||||
1. Complete the **Configure Ping Account** form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
|
||||
|
||||
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
|
||||
|
||||
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
|
||||
|
||||
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
|
||||
|
||||
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
|
||||
|
||||
1. **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 **Authenticate with Ping**, which is at the bottom of the page.
|
||||
|
||||
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.
|
||||
|
||||
>**Note:** You may have to disable your popup blocker to see the IdP login page.
|
||||
|
||||
**Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.
|
||||
|
||||
{{< saml_caveats >}}
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Local Authentication
|
||||
weight: 1111
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/authentication/local-authentication/
|
||||
---
|
||||
|
||||
Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the `admin` user that logs in to Rancher for the first time is a local user.
|
||||
|
||||
## Adding Local Users
|
||||
|
||||
Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.
|
||||
|
||||
1. From the **Global** view, select **Users** from the navigation bar.
|
||||
|
||||
2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done.
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Users and Groups
|
||||
weight: 1
|
||||
---
|
||||
|
||||
Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.
|
||||
|
||||
Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control](../../../../../pages-for-subheaders/manage-role-based-access-control-rbac.md).
|
||||
|
||||
## 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](create-local-users.md) user account, you will not be able to search for GitHub users or groups.
|
||||
|
||||
All users, whether they are local users or from an authentication provider, can be viewed and managed. From the **Global** view, click on **Users**.
|
||||
|
||||
{{< saml_caveats >}}
|
||||
|
||||
## User Information
|
||||
|
||||
Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.
|
||||
|
||||
Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.
|
||||
|
||||
### Automatically Refreshing User Information
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh. From the **Global** view, click on **Settings**. Two settings control this behavior:
|
||||
|
||||
- **`auth-user-info-max-age-seconds`**
|
||||
|
||||
This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to `3600` seconds, i.e. 1 hour.
|
||||
|
||||
- **`auth-user-info-resync-cron`**
|
||||
|
||||
This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *`, i.e. once a day at midnight. See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting.
|
||||
|
||||
|
||||
> **Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.
|
||||
|
||||
### Manually Refreshing User Information
|
||||
|
||||
If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.
|
||||
|
||||
1. From the **Global** view, click on **Users** in the navigation bar.
|
||||
|
||||
1. Click on **Refresh Group Memberships**.
|
||||
|
||||
**Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.
|
||||
|
||||
>**Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.
|
||||
|
||||
|
||||
## Session Length
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
The default length (TTL) of each user session is adjustable. The default session length is 16 hours.
|
||||
|
||||
1. From the **Global** view, click on **Settings**.
|
||||
1. In the **Settings** page, find **`auth-user-session-ttl-minutes`** and click **Edit.**
|
||||
1. Enter the amount of time in minutes a session length should last and click **Save.**
|
||||
|
||||
**Result:** Users are automatically logged out of Rancher after the set number of minutes.
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: 1. Configuring Microsoft AD FS for Rancher
|
||||
weight: 1205
|
||||
---
|
||||
|
||||
Before configuring Rancher to support AD FS users, you must add Rancher as a [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts) in AD FS.
|
||||
|
||||
1. Log into your AD server as an administrative user.
|
||||
|
||||
1. Open the **AD FS Management** console. Select **Add Relying Party Trust...** from the **Actions** menu and click **Start**.
|
||||
|
||||
|
||||
|
||||
1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party.
|
||||
|
||||
|
||||
|
||||
1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`.
|
||||
|
||||
|
||||
|
||||
1. Select **AD FS profile** as the configuration profile for your relying party trust.
|
||||
|
||||
|
||||
|
||||
1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
1. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
1. After reviewing your settings, select **Next** to add the relying party trust.
|
||||
|
||||
|
||||
|
||||
|
||||
1. Select **Open the Edit Claim Rules...** and click **Close**.
|
||||
|
||||
|
||||
|
||||
1. On the **Issuance Transform Rules** tab, click **Add Rule...**.
|
||||
|
||||
|
||||
|
||||
1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**.
|
||||
|
||||
|
||||
|
||||
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/>
|
||||
|
||||
|
||||
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](configure-rancher-for-ms-adfs.md)
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: 2. Configuring Rancher for Microsoft AD FS
|
||||
weight: 1205
|
||||
---
|
||||
_Available as of v2.0.7_
|
||||
|
||||
After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-for-rancher.md), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.
|
||||
|
||||
>**Important Notes For Configuring Your AD FS Server:**
|
||||
>
|
||||
>- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
|
||||
>- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
|
||||
>- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
|
||||
|
||||
|
||||
1. From the **Global** view, select **Security > Authentication** from the main menu.
|
||||
|
||||
1. Select **Microsoft Active Directory Federation Services**.
|
||||
|
||||
1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The [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 **Authenticate with AD FS**, which is at the bottom of the page.
|
||||
|
||||
Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.
|
||||
|
||||
>**Note:** You may have to disable your popup blocker to see the AD FS login page.
|
||||
|
||||
**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.
|
||||
|
||||
# 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"
|
||||
```
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Group Permissions with Shibboleth and OpenLDAP
|
||||
weight: 1
|
||||
---
|
||||
|
||||
_Available as of Rancher v2.4_
|
||||
|
||||
This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.
|
||||
|
||||
Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.
|
||||
|
||||
One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.
|
||||
|
||||
### Terminology
|
||||
|
||||
- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
|
||||
- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
|
||||
- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
|
||||
- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider.
|
||||
|
||||
### Adding OpenLDAP Group Permissions to Rancher Resources
|
||||
|
||||
The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.
|
||||
|
||||
For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.
|
||||
|
||||
In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.
|
||||
|
||||
When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.
|
||||
|
||||
Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.
|
||||
|
||||
|
||||
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Cluster Drivers
|
||||
weight: 1
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Cluster drivers are used to create clusters in a [hosted Kubernetes provider](../../../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md), 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](../manage-role-based-access-control-rbac/global-permissions.md)
|
||||
>- [Custom Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md#custom-global-permissions) with the [Manage Cluster Drivers](../manage-role-based-access-control-rbac/global-permissions.md) role assigned.
|
||||
|
||||
## Activating/Deactivating Cluster Drivers
|
||||
|
||||
By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.
|
||||
|
||||
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar.
|
||||
|
||||
2. From the **Drivers** page, select the **Cluster Drivers** tab.
|
||||
|
||||
3. Select the driver that you wish to **Activate** or **Deactivate** and select the appropriate icon.
|
||||
|
||||
## Adding Custom Cluster Drivers
|
||||
|
||||
If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create _hosted_ kubernetes clusters.
|
||||
|
||||
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar.
|
||||
|
||||
2. From the **Drivers** page select the **Cluster Drivers** tab.
|
||||
|
||||
3. Click **Add Cluster Driver**.
|
||||
|
||||
4. Complete the **Add Cluster Driver** form. Then click **Create**.
|
||||
|
||||
|
||||
### Developing your own Cluster Driver
|
||||
|
||||
In order to develop cluster driver to add to Rancher, please refer to our [example](https://github.com/rancher-plugins/kontainer-engine-driver-example).
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Node Drivers
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/concepts/global-configuration/node-drivers/
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/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.
|
||||
|
||||
#### Managing Node Drivers
|
||||
|
||||
>**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions:
|
||||
>
|
||||
>- [Administrator Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md)
|
||||
>- [Custom Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md#custom-global-permissions) with the [Manage Node Drivers](../manage-role-based-access-control-rbac/global-permissions.md) role assigned.
|
||||
|
||||
## Activating/Deactivating Node Drivers
|
||||
|
||||
By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.
|
||||
|
||||
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar. From the **Drivers** page, select the **Node Drivers** tab. In version before v2.2.0, you can select **Node Drivers** directly in the navigation bar.
|
||||
|
||||
2. Select the driver that you wish to **Activate** or **Deactivate** and select the appropriate icon.
|
||||
|
||||
## Adding Custom Node Drivers
|
||||
|
||||
If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.
|
||||
|
||||
1. From the **Global** view, choose **Tools > Drivers** in the navigation bar. From the **Drivers** page, select the **Node Drivers** tab. In version before v2.2.0, you can select **Node Drivers** directly in the navigation bar.
|
||||
|
||||
2. Click **Add Node Driver**.
|
||||
|
||||
3. Complete the **Add Node Driver** form. Then click **Create**.
|
||||
|
||||
### Developing your own node driver
|
||||
|
||||
Node drivers are implemented with [Docker Machine](https://docs.docker.com/machine/).
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Access and Sharing
|
||||
weight: 31
|
||||
---
|
||||
|
||||
If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.
|
||||
|
||||
Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.
|
||||
|
||||
When you share a template, each user can have one of two access levels:
|
||||
|
||||
- **Owner:** This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
|
||||
- **User:** These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as **Make Public (read-only),** all users in your Rancher setup have the User access level for the template.
|
||||
|
||||
If you create a template, you automatically become an owner of that template.
|
||||
|
||||
If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the [documentation about revising templates.](manage-rke1-templates.md)
|
||||
|
||||
There are several ways to share templates:
|
||||
|
||||
- Add users to a new RKE template during template creation
|
||||
- Add users to an existing RKE template
|
||||
- Make the RKE template public, sharing it with all users in the Rancher setup
|
||||
- Share template ownership with users who are trusted to modify the template
|
||||
|
||||
### Sharing Templates with Specific Users or Groups
|
||||
|
||||
To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template that you want to share and click the **⋮ > Edit.**
|
||||
1. In the **Share Template** section, click on **Add Member**.
|
||||
1. Search in the **Name** field for the user or group you want to share the template with.
|
||||
1. Choose the **User** access type.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The user or group can create clusters using the template.
|
||||
|
||||
### Sharing Templates with All Users
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template that you want to share and click the **⋮ > Edit.**
|
||||
1. Under **Share Template,** click **Make Public (read-only).** Then click **Save.**
|
||||
|
||||
**Result:** All users in the Rancher setup can create clusters using the template.
|
||||
|
||||
### Sharing Ownership of Templates
|
||||
|
||||
If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.
|
||||
|
||||
In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.
|
||||
|
||||
To give Owner access to a user or group,
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the RKE template that you want to share and click the **⋮ > 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.
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Applying Templates
|
||||
weight: 50
|
||||
---
|
||||
|
||||
You can create a cluster from an RKE template that you created, or from a template that has been [shared with you.](access-or-share-templates.md)
|
||||
|
||||
RKE templates can be applied to new clusters.
|
||||
|
||||
As of Rancher v2.3.3, you can [save the configuration of an existing cluster as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated.
|
||||
|
||||
You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Creating a cluster from an RKE template](#creating-a-cluster-from-an-rke-template)
|
||||
- [Updating a cluster created with an RKE template](#updating-a-cluster-created-with-an-rke-template)
|
||||
- [Converting an existing cluster to use an RKE template](#converting-an-existing-cluster-to-use-an-rke-template)
|
||||
|
||||
### Creating a Cluster from an RKE Template
|
||||
|
||||
To add a cluster [hosted by an infrastructure provider](../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) using an RKE template, use these steps:
|
||||
|
||||
1. From the **Global** view, go to the **Clusters** tab.
|
||||
1. Click **Add Cluster** and choose the infrastructure provider.
|
||||
1. Provide the cluster name and node template details as usual.
|
||||
1. To use an RKE template, under the **Cluster Options**, check the box for **Use an existing RKE template and revision.**
|
||||
1. Choose an existing template and revision from the dropdown menu.
|
||||
1. Optional: You can edit any settings that the RKE template owner marked as **Allow User Override** when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
|
||||
1. Click **Save** to launch the cluster.
|
||||
|
||||
### Updating a Cluster Created with an RKE Template
|
||||
|
||||
When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.
|
||||
|
||||
- If the setting allows a user override, you can update these settings in the cluster by [editing the cluster.](../../../../pages-for-subheaders/cluster-configuration.md)
|
||||
- If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.
|
||||
|
||||
If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.
|
||||
|
||||
As of Rancher v2.3.3, an existing cluster's settings can be [saved as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) In that situation, you can also edit the cluster to update the cluster to a new revision of the template.
|
||||
|
||||
> **Note:** You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
|
||||
|
||||
### Converting an Existing Cluster to Use an RKE Template
|
||||
|
||||
_Available as of v2.3.3_
|
||||
|
||||
This section describes how to create an RKE template from an existing cluster.
|
||||
|
||||
RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,](manage-rke1-templates.md#updating-a-template) and the cluster is upgraded to [use a newer version of the template.](manage-rke1-templates.md#upgrading-a-cluster-to-use-a-new-template-revision)
|
||||
|
||||
To convert an existing cluster to use an RKE template,
|
||||
|
||||
1. From the **Global** view in Rancher, click the **Clusters** tab.
|
||||
1. Go to the cluster that will be converted to use an RKE template. Click **⋮** > **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.](apply-templates.md#creating-a-cluster-from-an-rke-template)
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Template Creator Permissions
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.
|
||||
|
||||
For more information on administrator permissions, refer to the [documentation on global permissions](../manage-role-based-access-control-rbac/global-permissions.md).
|
||||
|
||||
# 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.](access-or-share-templates.md)
|
||||
|
||||
Administrators can give users permission to create RKE templates in two ways:
|
||||
|
||||
- By editing the permissions of an [individual user](#allowing-a-user-to-create-templates)
|
||||
- By changing the [default permissions of new users](#allowing-new-users-to-create-templates-by-default)
|
||||
|
||||
### Allowing a User to Create Templates
|
||||
|
||||
An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps:
|
||||
|
||||
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **⋮ > Edit.**
|
||||
1. In the **Global Permissions** section, choose **Custom** and select the **Create RKE Templates** role along with any other roles the user should have. Click **Save.**
|
||||
|
||||
**Result:** The user has permission to create RKE templates.
|
||||
|
||||
### Allowing New Users to Create Templates by Default
|
||||
|
||||
Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.
|
||||
|
||||
1. From the **Global** view, click **Security > Roles.**
|
||||
1. Under the **Global** roles tab, go to the role **Create RKE Templates** and click the **⋮ > Edit**.
|
||||
1. Select the option **Yes: Default role for new users** and click **Save.**
|
||||
|
||||
**Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.
|
||||
|
||||
### Revoking Permission to Create Templates
|
||||
|
||||
Administrators can remove a user's permission to create templates with the following steps:
|
||||
|
||||
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **⋮ > Edit.**
|
||||
1. In the **Global Permissions** section, un-check the box for **Create RKE Templates**. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The user cannot create RKE templates.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Template Enforcement
|
||||
weight: 32
|
||||
---
|
||||
|
||||
This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.
|
||||
|
||||
By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,
|
||||
|
||||
- Only an administrator has the ability to create clusters without a template.
|
||||
- All standard users must use an RKE template to create a new cluster.
|
||||
- Standard users cannot create a cluster without using a template.
|
||||
|
||||
Users can only create new templates if the administrator [gives them permission.](creator-permissions.md#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](apply-templates.md#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.](manage-rke1-templates.md#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](../manage-role-based-access-control-rbac/global-permissions.md) will use the Kubernetes and/or Rancher settings that are vetted by administrators.
|
||||
|
||||
To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:
|
||||
|
||||
1. From the **Global** view, click the **Settings** tab.
|
||||
1. Go to the `cluster-template-enforcement` setting. Click the vertical **⋮** and click **Edit.**
|
||||
1. Set the value to **True** and click **Save.**
|
||||
|
||||
**Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator.
|
||||
|
||||
# Disabling RKE Template Enforcement
|
||||
|
||||
To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:
|
||||
|
||||
1. From the **Global** view, click the **Settings** tab.
|
||||
1. Go to the `cluster-template-enforcement` setting. Click the vertical **⋮** and click **Edit.**
|
||||
1. Set the value to **False** and click **Save.**
|
||||
|
||||
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Example Scenarios
|
||||
weight: 5
|
||||
---
|
||||
|
||||
These example scenarios describe how an organization could use templates to standardize cluster creation.
|
||||
|
||||
- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone](#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings.
|
||||
- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,](#templates-for-basic-and-advanced-users) so that basic users have more restricted options and advanced users have more discretion when creating clusters.
|
||||
- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision](#updating-templates-and-clusters-created-with-them) and clusters created from the template can upgrade to the new version of the template.
|
||||
- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how [template ownership can be shared.](#allowing-other-users-to-control-and-share-a-template)
|
||||
|
||||
|
||||
# Enforcing a Template Setting for Everyone
|
||||
|
||||
Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.
|
||||
|
||||
1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as **Allow User Override**.
|
||||
1. The administrator makes the template public.
|
||||
1. The administrator turns on template enforcement.
|
||||
|
||||
**Results:**
|
||||
|
||||
- All Rancher users in the organization have access to the template.
|
||||
- All new clusters created by [standard users](../manage-role-based-access-control-rbac/global-permissions.md) 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.](enforce-templates.md#requiring-new-clusters-to-use-an-rke-template) This means that every [standard user](../manage-role-based-access-control-rbac/global-permissions.md) 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.](access-or-share-templates.md#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](manage-rke1-templates.md#updating-a-template) when the best practices change
|
||||
- [Disable outdated revisions](manage-rke1-templates.md#disabling-a-template-revision) of the template so that no new clusters can be created with it
|
||||
- [Delete the whole template](manage-rke1-templates.md#deleting-a-template) if the organization wants to go in a different direction
|
||||
- [Set a certain revision as default](manage-rke1-templates.md#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](access-or-share-templates.md) with specific users, make the template available to all Rancher users, or share ownership of the template with another user.
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: RKE Templates and Infrastructure
|
||||
weight: 90
|
||||
---
|
||||
|
||||
In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.
|
||||
|
||||
Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.
|
||||
|
||||
If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.
|
||||
|
||||
### Node Templates
|
||||
|
||||
[Node templates](../../../../reference-guides/user-settings/manage-node-templates.md) 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,](../../../../pages-for-subheaders/rancher-security.md) 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.
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Creating and Revising Templates
|
||||
weight: 32
|
||||
---
|
||||
|
||||
This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the **Global** view under **Tools > RKE Templates.**
|
||||
|
||||
Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.
|
||||
|
||||
Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.
|
||||
|
||||
The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Creating a template](#creating-a-template)
|
||||
- [Updating a template](#updating-a-template)
|
||||
- [Deleting a template](#deleting-a-template)
|
||||
- [Creating a revision based on the default revision](#creating-a-revision-based-on-the-default-revision)
|
||||
- [Creating a revision based on a cloned revision](#creating-a-revision-based-on-a-cloned-revision)
|
||||
- [Disabling a template revision](#disabling-a-template-revision)
|
||||
- [Re-enabling a disabled template revision](#re-enabling-a-disabled-template-revision)
|
||||
- [Setting a template revision as default](#setting-a-template-revision-as-default)
|
||||
- [Deleting a template revision](#deleting-a-template-revision)
|
||||
- [Upgrading a cluster to use a new template revision](#upgrading-a-cluster-to-use-a-new-template-revision)
|
||||
- [Exporting a running cluster to a new RKE template and revision](#exporting-a-running-cluster-to-a-new-rke-template-and-revision)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
You can create RKE templates if you have the **Create RKE Templates** permission, which can be [given by an administrator.](creator-permissions.md)
|
||||
|
||||
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.](access-or-share-templates.md#sharing-ownership-of-templates)
|
||||
|
||||
### Creating a Template
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Click **Add Template.**
|
||||
1. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
|
||||
1. Optional: Share the template with other users or groups by [adding them as members.](access-or-share-templates.md#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](../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md). After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck **Use an existing RKE Template and Revision** will be unavailable.
|
||||
|
||||
### Updating a Template
|
||||
|
||||
When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.
|
||||
|
||||
You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can [disable it.](#disabling-a-template-revision)
|
||||
|
||||
When new template revisions are created, clusters using an older revision of the template are unaffected.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template that you want to edit and click the **⋮ > Edit.**
|
||||
1. Edit the required information and click **Save.**
|
||||
1. Optional: You can change the default revision of this template and also change who it is shared with.
|
||||
|
||||
**Result:** The template is updated. To apply it to a cluster using an older version of the template, refer to the section on [upgrading a cluster to use a new revision of a template.](#upgrading-a-cluster-to-use-a-new-template-revision)
|
||||
|
||||
### Deleting a Template
|
||||
|
||||
When you no longer use an RKE template for any of your clusters, you can delete it.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the RKE template that you want to delete and click the **⋮ > Delete.**
|
||||
1. Confirm the deletion when prompted.
|
||||
|
||||
**Result:** The template is deleted.
|
||||
|
||||
### Creating a Revision Based on the Default Revision
|
||||
|
||||
You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the RKE template that you want to clone and click the **⋮ > New Revision From Default.**
|
||||
1. Complete the rest of the form to create a new revision.
|
||||
|
||||
**Result:** The RKE template revision is cloned and configured.
|
||||
|
||||
### Creating a Revision Based on a Cloned Revision
|
||||
|
||||
When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template revision you want to clone. Then select **⋮ > Clone Revision.**
|
||||
1. Complete the rest of the form.
|
||||
|
||||
**Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.
|
||||
|
||||
### Disabling a Template Revision
|
||||
|
||||
When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.
|
||||
|
||||
You can disable the revision if it is not being used by any cluster.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template revision you want to disable. Then select **⋮ > Disable.**
|
||||
|
||||
**Result:** The RKE template revision cannot be used to create a new cluster.
|
||||
|
||||
### Re-enabling a Disabled Template Revision
|
||||
|
||||
If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the template revision you want to re-enable. Then select **⋮ > Enable.**
|
||||
|
||||
**Result:** The RKE template revision can be used to create a new cluster.
|
||||
|
||||
### Setting a Template Revision as Default
|
||||
|
||||
When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.
|
||||
|
||||
To set an RKE template revision as default,
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the RKE template revision that should be default and click the **⋮ > Set as Default.**
|
||||
|
||||
**Result:** The RKE template revision will be used as the default option when clusters are created with the template.
|
||||
|
||||
### Deleting a Template Revision
|
||||
|
||||
You can delete all revisions of a template except for the default revision.
|
||||
|
||||
To permanently delete a revision,
|
||||
|
||||
1. From the **Global** view, click **Tools > RKE Templates.**
|
||||
1. Go to the RKE template revision that should be deleted and click the **⋮ > 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.](apply-templates.md)
|
||||
> This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available.
|
||||
|
||||
To upgrade a cluster to use a new template revision,
|
||||
|
||||
1. From the **Global** view in Rancher, click the **Clusters** tab.
|
||||
1. Go to the cluster that you want to upgrade and click **⋮ > Edit.**
|
||||
1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The cluster is upgraded to use the settings defined in the new template revision.
|
||||
|
||||
### Exporting a Running Cluster to a New RKE Template and Revision
|
||||
|
||||
You can save an existing cluster's settings as an RKE template.
|
||||
|
||||
This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,](manage-rke1-templates.md#updating-a-template) and the cluster is upgraded to [use a newer version of the template.]
|
||||
|
||||
To convert an existing cluster to use an RKE template,
|
||||
|
||||
1. From the **Global** view in Rancher, click the **Clusters** tab.
|
||||
1. Go to the cluster that will be converted to use an RKE template. Click **⋮** > **Save as RKE Template.**
|
||||
1. Enter a name for the template in the form that appears, and click **Create.**
|
||||
|
||||
**Results:**
|
||||
|
||||
- A new RKE template is created.
|
||||
- The cluster is converted to use the new template.
|
||||
- New clusters can be [created from the new template and revision.](apply-templates.md#creating-a-cluster-from-an-rke-template)
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Overriding Template Settings
|
||||
weight: 33
|
||||
---
|
||||
|
||||
When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as **Allow User Override.**
|
||||
|
||||
After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as **Allow User Override.** However, if the template is [updated to a new revision](manage-rke1-templates.md) 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
|
||||
+89
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Pod Security Policies
|
||||
weight: 1135
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/concepts/global-configuration/pod-security-policies/
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/pod-security-policies/
|
||||
- /rancher/v2.0-v2.4/en/tasks/clusters/adding-a-pod-security-policy/
|
||||
---
|
||||
|
||||
_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](#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
|
||||
|
||||
_Available as of v2.0.7_
|
||||
|
||||
Rancher ships with two default Pod Security Policies (PSPs): the `restricted` and `unrestricted` policies.
|
||||
|
||||
### Restricted
|
||||
|
||||
This policy is based on the Kubernetes [example restricted policy](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml). It significantly restricts what types of pods can be deployed to a cluster or project. This policy:
|
||||
|
||||
- Prevents pods from running as a privileged user and prevents escalation of privileges.
|
||||
- Validates that server-required security mechanisms are in place (such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.
|
||||
|
||||
### Unrestricted
|
||||
|
||||
This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.
|
||||
|
||||
# Creating 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.](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md)
|
||||
|
||||
You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by [editing the cluster.](../../../pages-for-subheaders/cluster-configuration.md)
|
||||
|
||||
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. From the **Global** view, select **Security** > **Pod Security Policies** from the main menu. Then click **Add Policy**.
|
||||
|
||||
**Step Result:** The **Add Policy** form opens.
|
||||
|
||||
2. Name the policy.
|
||||
|
||||
3. Complete each section of the form. Refer to the [Kubernetes documentation]((https://kubernetes.io/docs/concepts/policy/pod-security-policy/)) for more information on what each policy does.
|
||||
|
||||
|
||||
# Configuration
|
||||
|
||||
The Kubernetes documentation on PSPs is [here.](https://kubernetes.io/docs/concepts/policy/pod-security-policy/)
|
||||
|
||||
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[1]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
|
||||
[2]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces
|
||||
[3]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#users-and-groups
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Configuring a Global Default Private Registry
|
||||
weight: 400
|
||||
aliases:
|
||||
---
|
||||
|
||||
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 Docker installation](installation/air-gap-single-node) or [air gapped Kubernetes installation](installation/air-gap-high-availability) instructions.
|
||||
|
||||
If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to [pass in the registry credentials through the advanced cluster options](#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. Go into the **Settings** view.
|
||||
|
||||
|
||||
|
||||
1. Look for the setting called `system-default-registry` and choose **Edit**.
|
||||
|
||||
|
||||
|
||||
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 provision a cluster with Rancher:
|
||||
|
||||
1. When you create a cluster through the Rancher UI, go to the **Cluster Options** section and click **Show Advanced Options.**
|
||||
1. In the <b>Enable Private Registries</b> section, click **Enabled.**
|
||||
1. Enter the registry URL and credentials.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The new cluster will be able to pull images from the private registry.
|
||||
+193
@@ -0,0 +1,193 @@
|
||||
---
|
||||
title: Cluster and Project Roles
|
||||
weight: 1127
|
||||
---
|
||||
|
||||
Cluster and project roles define user authorization inside a cluster or project. You can manage these roles from the **Global > Security > Roles** page.
|
||||
|
||||
### Membership and Role Assignment
|
||||
|
||||
The projects and clusters accessible to non-administrative users is determined by _membership_. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.
|
||||
|
||||
When you create a cluster or project, Rancher automatically assigns you as the `Owner` for it. Users assigned the `Owner` role can assign other users roles in the cluster or project.
|
||||
|
||||
> **Note:** Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.
|
||||
|
||||
### Cluster Roles
|
||||
|
||||
_Cluster roles_ are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: `Owner` and `Member`.
|
||||
|
||||
- **Cluster Owner:**
|
||||
|
||||
These users have full control over the cluster and all resources in it.
|
||||
|
||||
- **Cluster Member:**
|
||||
|
||||
These users can view most cluster level resources and create new projects.
|
||||
|
||||
#### Custom Cluster Roles
|
||||
|
||||
Rancher lets you assign _custom cluster roles_ to a standard user instead of the typical `Owner` or `Member` roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.
|
||||
|
||||
#### Cluster Role Reference
|
||||
|
||||
The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, `Cluster Owner` and `Cluster Member`.
|
||||
|
||||
| Built-in Cluster Role | Owner | Member <a id="clus-roles"></a> |
|
||||
| ---------------------------------- | ------------- | --------------------------------- |
|
||||
| Create Projects | ✓ | ✓ |
|
||||
| Manage Cluster Backups | ✓ | |
|
||||
| Manage Cluster Catalogs | ✓ | |
|
||||
| Manage Cluster Members | ✓ | |
|
||||
| Manage Nodes | ✓ | |
|
||||
| Manage Storage | ✓ | |
|
||||
| View All Projects | ✓ | |
|
||||
| View Cluster Catalogs | ✓ | ✓ |
|
||||
| View Cluster Members | ✓ | ✓ |
|
||||
| View Nodes | ✓ | ✓ |
|
||||
|
||||
For details on how each cluster role can access Kubernetes resources, you can go to the **Global** view in the Rancher UI. Then click **Security > Roles** and go to the **Clusters** tab. If you click an individual role, you can refer to the **Grant Resources** table to see all of the operations and resources that are permitted by the role.
|
||||
|
||||
> **Note:**
|
||||
>When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
|
||||
|
||||
### Giving a Custom Cluster Role to a Cluster Member
|
||||
|
||||
After an administrator [sets up a custom cluster role,](custom-roles.md) cluster owners and admins can then assign those roles to cluster members.
|
||||
|
||||
To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.
|
||||
|
||||
To assign the role to a new cluster member,
|
||||
|
||||
1. Go to the **Cluster** view, then go to the **Members** tab.
|
||||
1. Click **Add Member.** Then in the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The member has the assigned role.
|
||||
|
||||
To assign any custom role to an existing cluster member,
|
||||
|
||||
1. Go to the member you want to give the role to. Click the **⋮ > View in API.**
|
||||
1. In the **roleTemplateId** field, go to the drop-down menu and choose the role you want to assign to the member. Click **Show Request** and **Send Request.**
|
||||
|
||||
**Result:** The member has the assigned role.
|
||||
|
||||
### Project Roles
|
||||
|
||||
_Project roles_ are roles that can be used to grant users access to a project. There are three primary project roles: `Owner`, `Member`, and `Read Only`.
|
||||
|
||||
- **Project Owner:**
|
||||
|
||||
These users have full control over the project and all resources in it.
|
||||
|
||||
- **Project Member:**
|
||||
|
||||
These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.
|
||||
|
||||
>**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](custom-roles.md) 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](locked-roles.md) a default role, the system still assigns the role to users who create a cluster/project.
|
||||
>- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.
|
||||
|
||||
### Configuring Default Roles for Cluster and Project Creators
|
||||
|
||||
You can change the cluster or project role(s) that are automatically assigned to the creating user.
|
||||
|
||||
1. From the **Global** view, select **Security > Roles** from the main menu. Select either the **Cluster** or **Project** tab.
|
||||
|
||||
1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **⋮ > Edit**.
|
||||
|
||||
1. Enable the role as default.
|
||||
<details id="cluster">
|
||||
<summary>For Clusters</summary>
|
||||
|
||||
1. From **Cluster Creator Default**, choose **Yes: Default role for new cluster creation**.
|
||||
1. Click **Save**.
|
||||
|
||||
</details>
|
||||
<details id="project">
|
||||
|
||||
<summary>For Projects</summary>
|
||||
1. From **Project Creator Default**, choose **Yes: Default role for new project creation**.
|
||||
1. Click **Save**.
|
||||
|
||||
</details>
|
||||
|
||||
1. If you want to remove a default role, edit the permission and select **No** from the default roles option.
|
||||
|
||||
**Result:** The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the **Cluster/Project Creator Default** column.
|
||||
|
||||
### Cluster Membership Revocation Behavior
|
||||
|
||||
When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster _and_ a project within the cluster, that standard user [loses their cluster roles](#clus-roles) but [retains their project roles](#proj-roles). In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:
|
||||
|
||||
- Access the projects they hold membership in.
|
||||
- Exercise any [individual project roles](#project-role-reference) they are assigned.
|
||||
|
||||
If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.
|
||||
+179
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: Custom Roles
|
||||
weight: 1128
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/roles/
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
Within Rancher, _roles_ determine what actions a user can make within a cluster or project.
|
||||
|
||||
Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Creating a custom role for a cluster or project](#creating-a-custom-role-for-a-cluster-or-project)
|
||||
- [Creating a custom global role](#creating-a-custom-global-role)
|
||||
- [Deleting a custom global role](#deleting-a-custom-global-role)
|
||||
- [Assigning a custom global role to a group](#assigning-a-custom-global-role-to-a-group)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To complete the tasks on this page, one of the following permissions are required:
|
||||
|
||||
- [Administrator Global Permissions](global-permissions.md).
|
||||
- [Custom Global Permissions](global-permissions.md#custom-global-permissions) with the [Manage Roles](global-permissions.md) role assigned.
|
||||
|
||||
## Creating A Custom Role for a Cluster or Project
|
||||
|
||||
While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.
|
||||
|
||||
The steps to add custom roles differ depending on the version of Rancher.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.0.7+">
|
||||
|
||||
1. From the **Global** view, select **Security > Roles** from the main menu.
|
||||
|
||||
1. Select a tab to determine the scope of the roles you're adding. The tabs are:
|
||||
|
||||
- **Cluster:** The role is valid for assignment when adding/managing members to _only_ clusters.
|
||||
- **Project:** The role is valid for assignment when adding/managing members to _only_ projects.
|
||||
|
||||
1. Click **Add Cluster/Project Role.**
|
||||
|
||||
1. **Name** the role.
|
||||
|
||||
1. Optional: Choose the **Cluster/Project Creator Default** option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.
|
||||
|
||||
> Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively.
|
||||
|
||||
1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role.
|
||||
|
||||
> When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
|
||||
|
||||
> 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 a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.
|
||||
|
||||
1. Click **Create**.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.0.7">
|
||||
|
||||
1. From the **Global** view, select **Security > Roles** from the main menu.
|
||||
|
||||
1. Click **Add Role**.
|
||||
|
||||
1. **Name** the role.
|
||||
|
||||
1. Choose whether to set the role to a status of [locked](locked-roles.md).
|
||||
|
||||
> **Note:** Locked roles cannot be assigned to users.
|
||||
|
||||
1. In the **Context** dropdown menu, choose the scope of the role assigned to the user. The contexts are:
|
||||
|
||||
- **All:** The user can use their assigned role regardless of context. This role is valid for assignment when adding/managing members to clusters or projects.
|
||||
|
||||
- **Cluster:** This role is valid for assignment when adding/managing members to _only_ clusters.
|
||||
|
||||
- **Project:** This role is valid for assignment when adding/managing members to _only_ projects.
|
||||
|
||||
1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role.
|
||||
|
||||
> When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
|
||||
|
||||
> 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 a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.
|
||||
|
||||
1. Click **Create**.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Creating a Custom Global Role
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
### Creating a Custom Global Role that Copies Rules from an Existing Role
|
||||
|
||||
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.
|
||||
|
||||
The custom global role can then be assigned to a user or group so that the custom global role takes effect the first time the user or users sign into Rancher.
|
||||
|
||||
To create a custom global role based on an existing role,
|
||||
|
||||
1. Go to the **Global** view and click **Security > Roles.**
|
||||
1. On the **Global** tab, go to the role that the custom global role will be based on. Click **⋮ (…) > Clone.**
|
||||
1. Enter a name for the role.
|
||||
1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.**
|
||||
1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role.
|
||||
|
||||
> 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. Click **Save.**
|
||||
|
||||
### Creating a Custom Global Role that Does Not Copy Rules from Another Role
|
||||
|
||||
Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:
|
||||
|
||||
1. Go to the **Global** view and click **Security > Roles.**
|
||||
1. On the **Global** tab, click **Add Global Role.**
|
||||
1. Enter a name for the role.
|
||||
1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.**
|
||||
1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role.
|
||||
|
||||
> 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. Click **Save.**
|
||||
|
||||
## Deleting a Custom Global Role
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
When deleting a custom global role, all global role bindings with this custom role are deleted.
|
||||
|
||||
If a user is only assigned one custom global role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.
|
||||
|
||||
Custom global roles can be deleted, but built-in roles cannot be deleted.
|
||||
|
||||
To delete a custom global role,
|
||||
|
||||
1. Go to the **Global** view and click **Security > Roles.**
|
||||
2. On the **Global** tab, go to the custom global role that should be deleted and click **⋮ (…) > Delete.**
|
||||
3. Click **Delete.**
|
||||
|
||||
## Assigning a Custom Global Role to a Group
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.
|
||||
|
||||
When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.
|
||||
|
||||
If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have their individual Standard User role.
|
||||
|
||||
> **Prerequisites:** You can only assign a global role to a group if:
|
||||
>
|
||||
> * You have set up an [external authentication provider](../../../../pages-for-subheaders/about-authentication.md#external-vs-local-authentication)
|
||||
> * The external authentication provider supports [user groups](../about-authentication/authentication-config/manage-users-and-groups.md)
|
||||
> * You have already set up at least one user group with the authentication provider
|
||||
|
||||
To assign a custom global role to a group, follow these steps:
|
||||
|
||||
1. From the **Global** view, go to **Security > Groups.**
|
||||
1. Click **Assign Global Role.**
|
||||
1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role.
|
||||
1. In the **Custom** section, choose any custom global role that will be assigned to the group.
|
||||
1. Optional: In the **Global Permissions** or **Built-in** sections, select any additional permissions that the group should have.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The custom global role will take effect when the users in the group log into Rancher.
|
||||
+174
@@ -0,0 +1,174 @@
|
||||
---
|
||||
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 three default global permissions: `Administrator`, `Standard User` and `User-base`.
|
||||
|
||||
- **Administrator:** These users have full control over the entire Rancher system and all clusters within it.
|
||||
|
||||
- <a id="user"></a>**Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.
|
||||
|
||||
- **User-Base:** User-Base users have login-access only.
|
||||
|
||||
You cannot update or delete the built-in Global Permissions.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Global permission assignment](#global-permission-assignment)
|
||||
- [Global permissions for new local users](#global-permissions-for-new-local-users)
|
||||
- [Global permissions for users with external authentication](#global-permissions-for-users-with-external-authentication)
|
||||
- [Custom global permissions](#custom-global-permissions)
|
||||
- [Custom global permissions reference](#custom-global-permissions-reference)
|
||||
- [Configuring default global permissions for new users](#configuring-default-global-permissions)
|
||||
- [Configuring global permissions for existing individual users](#configuring-global-permissions-for-existing-individual-users)
|
||||
- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
|
||||
- [Refreshing group memberships](#refreshing-group-memberships)
|
||||
|
||||
# Global Permission Assignment
|
||||
|
||||
Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.
|
||||
|
||||
### Global Permissions for New Local Users
|
||||
|
||||
When you create a new local user, you assign them a global permission as you complete the **Add User** form.
|
||||
|
||||
To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column. You can [change the default global permissions to meet your needs.](#configuring-default-global-permissions)
|
||||
|
||||
### Global Permissions for Users with External Authentication
|
||||
|
||||
When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the **New User Default** global permissions. By default, Rancher assigns the **Standard User** permission for new users.
|
||||
|
||||
To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column, and you can [change them to meet your needs.](#configuring-default-global-permissions)
|
||||
|
||||
Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users)
|
||||
|
||||
As of Rancher v2.4.0, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups.
|
||||
|
||||
# Custom Global Permissions
|
||||
|
||||
Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.
|
||||
|
||||
When a user from an [external authentication source](../../../../pages-for-subheaders/about-authentication.md) 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) | ✓ | ✓ | |
|
||||
|
||||
> \*This role has two names:
|
||||
>
|
||||
> - When you go to the <b>Users</b> tab and edit a user's global role, this role is called <b>Login Access</b> in the custom global permissions list.
|
||||
> - When you go to the <b>Security</b> tab and edit the roles from the roles page, this role is called <b>User Base.</b>
|
||||
|
||||
For details on which Kubernetes resources correspond to each global permission, you can go to the **Global** view in the Rancher UI. Then click **Security > Roles** and go to the **Global** tab. If you click an individual role, you can refer to the **Grant Resources** table to see all of the operations and resources that are permitted by the role.
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`.
|
||||
> - When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
|
||||
|
||||
### Configuring Default Global Permissions
|
||||
|
||||
If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.
|
||||
|
||||
> **Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.
|
||||
|
||||
To change the default global permissions that are assigned to external users upon their first log in, follow these steps:
|
||||
|
||||
1. From the **Global** view, select **Security > Roles** from the main menu. Make sure the **Global** tab is selected.
|
||||
|
||||
1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **⋮ > Edit**.
|
||||
|
||||
1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**.
|
||||
|
||||
1. If you want to remove a default permission, edit the permission and select **No** from **New User Default**.
|
||||
|
||||
**Result:** The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the **New User Default** column.
|
||||
|
||||
### Configuring Global Permissions for Individual Users
|
||||
|
||||
To configure permission for a user,
|
||||
|
||||
1. Go to the **Users** tab.
|
||||
|
||||
1. On this page, go to the user whose access level you want to change and click **⋮ > Edit.**
|
||||
|
||||
1. In the **Global Permissions** section, click **Custom.**
|
||||
|
||||
1. Check the boxes for each subset of permissions you want the user to have access to.
|
||||
|
||||
1. Click **Save.**
|
||||
|
||||
> **Result:** The user's global permissions have been updated.
|
||||
|
||||
### Configuring Global Permissions for Groups
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.
|
||||
|
||||
After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.
|
||||
|
||||
For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator [refreshes the group memberships.](#refreshing-group-memberships)
|
||||
|
||||
For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the **New User Default** global permissions. By default, the **New User Default** permissions are equivalent to the **Standard User** global role, but the default permissions can be [configured.](#configuring-default-global-permissions)
|
||||
|
||||
If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default.** Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,](#refreshing-group-memberships) whichever comes first.
|
||||
|
||||
> **Prerequisites:** You can only assign a global role to a group if:
|
||||
>
|
||||
> * You have set up an [external authentication provider](../../../../pages-for-subheaders/about-authentication.md#external-vs-local-authentication)
|
||||
> * The external authentication provider supports [user groups](../about-authentication/authentication-config/manage-users-and-groups.md)
|
||||
> * You have already set up at least one user group with the authentication provider
|
||||
|
||||
To assign a custom global role to a group, follow these steps:
|
||||
|
||||
1. From the **Global** view, go to **Security > Groups.**
|
||||
1. Click **Assign Global Role.**
|
||||
1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role.
|
||||
1. In the **Global Permissions,** **Custom,** and/or **Built-in** sections, select the permissions that the group should have.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** The custom global role will take effect when the users in the group log into Rancher.
|
||||
|
||||
### Refreshing Group Memberships
|
||||
|
||||
When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.
|
||||
|
||||
To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.
|
||||
|
||||
An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.
|
||||
|
||||
To refresh group memberships,
|
||||
|
||||
1. From the **Global** view, click **Security > Users.**
|
||||
1. Click **Refresh Group Memberships.**
|
||||
|
||||
**Result:** Any changes to the group members' permissions will take effect.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Locked Roles
|
||||
weight: 1129
|
||||
---
|
||||
|
||||
You can set roles to a status of `locked`. Locking roles prevent them from being assigned users in the future.
|
||||
|
||||
Locked roles:
|
||||
|
||||
- Cannot be assigned to users that don't already have it assigned.
|
||||
- Are not listed in the **Member Roles** drop-down when you are adding a user to a cluster or project.
|
||||
- Do not affect users assigned the role before you lock the role. These users retain access that the role provides.
|
||||
|
||||
**Example:** let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.
|
||||
|
||||
To enforce it, before you add new users to the cluster, you should lock the following roles: `Cluster Owner`, `Cluster Member`, and `Create Projects`. Then you could create a new custom role that includes the same permissions as a __Cluster Member__, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.
|
||||
|
||||
Roles can be locked by the following users:
|
||||
|
||||
- Any user assigned the `Administrator` global permission.
|
||||
- Any user assigned the `Custom Users` permission, along with the `Manage Roles` role.
|
||||
|
||||
|
||||
## Locking/Unlocking Roles
|
||||
|
||||
If you want to prevent a role from being assigned to users, you can set it to a status of `locked`.
|
||||
|
||||
You can lock roles in two contexts:
|
||||
|
||||
- When you're [adding a custom role](custom-roles.md).
|
||||
- When you editing an existing role (see below).
|
||||
|
||||
1. From the **Global** view, select **Security** > **Roles**.
|
||||
|
||||
2. From the role that you want to lock (or unlock), select **⋮** > **Edit**.
|
||||
|
||||
3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**.
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+1
@@ -0,0 +1 @@
|
||||
<!-- PLACEHOLDER -->
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Enable Istio with Pod Security Policies
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/enable-istio-with-psp
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/enable-istio-in-cluster/enable-istio-with-psp
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-cluster/enable-istio-with-psp
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-cluster/enable-istio-with-psp/
|
||||
---
|
||||
|
||||
>**Note:** The following guide is only for RKE provisioned clusters.
|
||||
|
||||
If you have restrictive Pod Security Policies enabled, then Istio may not be able to function correctly, because it needs certain permissions in order to install itself and manage pod infrastructure. In this section, we will configure a cluster with PSPs enabled for an Istio install, and also set up the Istio CNI plugin.
|
||||
|
||||
The Istio CNI plugin removes the need for each application pod to have a privileged `NET_ADMIN` container. For further information, see the [Istio CNI Plugin docs](https://istio.io/docs/setup/additional-setup/cni). Please note that the [Istio CNI Plugin is in alpha](https://istio.io/about/feature-stages/).
|
||||
|
||||
- 1. [Configure the System Project Policy to allow Istio install.](#1-configure-the-system-project-policy-to-allow-istio-install)
|
||||
- 2. [Install the CNI plugin in the System project.](#2-install-the-cni-plugin-in-the-system-project)
|
||||
- 3. [Install Istio.](#3-install-istio)
|
||||
|
||||
### 1. Configure the System Project Policy to allow Istio install
|
||||
|
||||
1. From the main menu of the **Dashboard**, select **Projects/Namespaces**.
|
||||
1. Find the **Project: System** project and select the **⋮ > Edit**.
|
||||
1. Change the Pod Security Policy option to be unrestricted, then click Save.
|
||||
|
||||
|
||||
### 2. Install the CNI Plugin in the System Project
|
||||
|
||||
1. From the main menu of the **Dashboard**, select **Projects/Namespaces**.
|
||||
1. Select the **Project: System** project.
|
||||
1. Choose **Tools > Catalogs** in the navigation bar.
|
||||
1. Add a catalog with the following:
|
||||
1. Name: istio-cni
|
||||
1. Catalog URL: https://github.com/istio/cni
|
||||
1. Branch: The branch that matches your current release, for example: `release-1.4`.
|
||||
1. From the main menu select **Apps**
|
||||
1. Click Launch and select istio-cni
|
||||
1. Update the namespace to be "kube-system"
|
||||
1. In the answers section, click "Edit as YAML" and paste in the following, then click launch:
|
||||
|
||||
```
|
||||
---
|
||||
logLevel: "info"
|
||||
excludeNamespaces:
|
||||
- "istio-system"
|
||||
- "kube-system"
|
||||
```
|
||||
|
||||
### 3. Install Istio
|
||||
|
||||
Follow the [primary instructions](enable-istio-in-cluster.md), adding a custom answer: `istio_cni.enabled: true`.
|
||||
|
||||
After Istio has finished installing, the Apps page in System Projects should show both istio and `istio-cni` applications deployed successfully. Sidecar injection will now be functional.
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: 1. Enable Istio in the Cluster
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/enable-istio-in-cluster
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-cluster
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-cluster/
|
||||
---
|
||||
|
||||
This cluster uses the default Nginx controller to allow traffic into the cluster.
|
||||
|
||||
A Rancher [administrator](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) can configure Rancher to deploy Istio in a Kubernetes cluster.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
This guide assumes you have already [installed Rancher,](../../../pages-for-subheaders/installation-and-upgrade.md) and you have already [provisioned a separate Kubernetes cluster](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) on which you will install Istio.
|
||||
|
||||
The nodes in your cluster must meet the [CPU and memory requirements.](../../../explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md)
|
||||
|
||||
The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)
|
||||
|
||||
> If the cluster has a Pod Security Policy enabled there are [additional prerequisites steps](enable-istio-in-cluster-with-psp.md)
|
||||
|
||||
# Enable Istio in the Cluster
|
||||
|
||||
1. From the **Global** view, navigate to the **cluster** where you want to enable Istio.
|
||||
1. Click **Tools > Istio.**
|
||||
1. Optional: Configure member access and [resource limits](../../../explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
|
||||
1. Click **Enable**.
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** Istio is enabled at the cluster level.
|
||||
|
||||
The Istio application, `cluster-istio`, is added as an application to the cluster's `system` project.
|
||||
|
||||
When Istio is enabled in the cluster, the label for Istio sidecar auto injection,`istio-injection=enabled`, will be automatically added to each new namespace in this cluster. This automatically enables Istio sidecar injection in all new workloads that are deployed in those namespaces. You will need to manually enable Istio in preexisting namespaces and workloads.
|
||||
|
||||
### [Next: Enable Istio in a Namespace](enable-istio-in-namespace.md)
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: 2. Enable Istio in a Namespace
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/enable-istio-in-namespace
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-namespace
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/enable-istio-in-namespace/
|
||||
---
|
||||
|
||||
You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.
|
||||
|
||||
This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.
|
||||
|
||||
> **Prerequisite:** To enable Istio in a namespace, the cluster must have Istio enabled.
|
||||
|
||||
1. In the Rancher UI, go to the cluster view. Click the **Projects/Namespaces** tab.
|
||||
1. Go to the namespace where you want to enable the Istio sidecar auto injection and click the **⋮.**
|
||||
1. Click **Edit.**
|
||||
1. In the **Istio sidecar auto injection** section, click **Enable.**
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The namespace now has the label `istio-injection=enabled`. All new workloads deployed in this namespace will have the Istio sidecar injected by default.
|
||||
|
||||
### Verifying that Automatic Istio Sidecar Injection is Enabled
|
||||
|
||||
To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the **Containers** section, you should see the `istio-proxy` container.
|
||||
|
||||
### Excluding Workloads from Being Injected with the Istio Sidecar
|
||||
|
||||
If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:
|
||||
|
||||
```
|
||||
sidecar.istio.io/inject: “false”
|
||||
```
|
||||
|
||||
To add the annotation to a workload,
|
||||
|
||||
1. From the **Global** view, open the project that has the workload that should not have the sidecar.
|
||||
1. Click **Resources > Workloads.**
|
||||
1. Go to the workload that should not have the sidecar and click **⋮ > Edit.**
|
||||
1. Click **Show Advanced Options.** Then expand the **Labels & Annotations** section.
|
||||
1. Click **Add Annotation.**
|
||||
1. In the **Key** field, enter `sidecar.istio.io/inject`.
|
||||
1. In the **Value** field, enter `false`.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The Istio sidecar will not be injected into the workload.
|
||||
|
||||
> **NOTE:** If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.
|
||||
|
||||
|
||||
### [Next: Select the Nodes ](node-selectors.md)
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: 7. Generate and View Traffic
|
||||
weight: 7
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/view-traffic
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/view-traffic
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/view-traffic
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/view-traffic/
|
||||
---
|
||||
|
||||
This section describes how to view the traffic that is being managed by Istio.
|
||||
|
||||
# The Kiali Traffic Graph
|
||||
|
||||
Rancher integrates a Kiali graph into the Rancher UI. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.
|
||||
|
||||
To see the traffic graph,
|
||||
|
||||
1. From the project view in Rancher, click **Resources > Istio.**
|
||||
1. Go to the **Traffic Graph** tab. This tab has the Kiali network visualization integrated into the UI.
|
||||
|
||||
If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to `v1` and `v3` of the `reviews` service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.
|
||||
|
||||
For additional tools and visualizations, you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.
|
||||
|
||||
# Viewing Traffic Metrics
|
||||
|
||||
Istio’s monitoring features provide visibility into the performance of all your services.
|
||||
|
||||
1. From the project view in Rancher, click **Resources > Istio.**
|
||||
1. Go to the **Traffic Metrics** tab. After traffic is generated in your cluster, you should be able to see metrics for **Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count** and **Request Duration.**
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: 3. Select the Nodes Where Istio Components Will be Deployed
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/node-selectors
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/node-selectors
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/node-selectors
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/node-selectors/
|
||||
---
|
||||
|
||||
> **Prerequisite:** Your cluster needs a worker node that can designated for Istio. The worker node should meet the [resource requirements.](../../../explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md)
|
||||
|
||||
This section describes how use node selectors to configure Istio components to be deployed on a designated node.
|
||||
|
||||
In larger deployments, it is strongly advised that Istio's infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.
|
||||
|
||||
# Adding a Label to the Istio Node
|
||||
|
||||
First, add a label to the node where Istio components should be deployed. This label can have any key-value pair. For this example, we will use the key `istio` and the value `enabled`.
|
||||
|
||||
1. From the cluster view, go to the **Nodes** tab.
|
||||
1. Go to a worker node that will host the Istio components and click **⋮ > Edit.**
|
||||
1. Expand the **Labels & Annotations** section.
|
||||
1. Click **Add Label.**
|
||||
1. In the fields that appear, enter `istio` for the key and `enabled` for the value.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** A worker node has the label that will allow you to designate it for Istio components.
|
||||
|
||||
# Configuring Istio Components to Use the Labeled Node
|
||||
|
||||
Configure each Istio component to be deployed to the node with the Istio label. Each Istio component can be configured individually, but in this tutorial, we will configure all of the components to be scheduled on the same node for the sake of simplicity.
|
||||
|
||||
For larger deployments, it is recommended to schedule each component of Istio onto separate nodes.
|
||||
|
||||
1. From the cluster view, click **Tools > Istio.**
|
||||
1. Expand the **Pilot** section and click **Add Selector** in the form that appears. Enter the node selector label that you added to the Istio node. In our case, we are using the key `istio` and the value `enabled.`
|
||||
1. Repeat the previous step for the **Mixer** and **Tracing** sections.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The Istio components will be deployed on the Istio node.
|
||||
|
||||
### [Next: Add Deployments and Services](use-istio-sidecar.md)
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: 5. Set up the Istio Gateway
|
||||
weight: 5
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/gateway
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/gateway
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/gateway
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/gateway/
|
||||
---
|
||||
|
||||
The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.
|
||||
|
||||
You can use the NGINX ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.
|
||||
|
||||
To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two ingresses.
|
||||
|
||||
You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.
|
||||
|
||||
You can route traffic into the service mesh with a load balancer or just Istio's NodePort gateway. This section describes how to set up the NodePort gateway.
|
||||
|
||||
For more information on the Istio gateway, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/gateway/)
|
||||
|
||||
|
||||
|
||||
# Enable the Istio Gateway
|
||||
|
||||
The ingress gateway is a Kubernetes service that will be deployed in your cluster. There is only one Istio gateway per cluster.
|
||||
|
||||
1. Go to the cluster where you want to allow outside traffic into Istio.
|
||||
1. Click **Tools > Istio.**
|
||||
1. Expand the **Ingress Gateway** section.
|
||||
1. Under **Enable Ingress Gateway,** click **True.** The default type of service for the Istio gateway is NodePort. You can also configure it as a [load balancer.](../../new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md)
|
||||
1. Optionally, configure the ports, service types, node selectors and tolerations, and resource requests and limits for this service. The default resource requests for CPU and memory are the minimum recommended resources.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The gateway is deployed, which allows Istio to receive traffic from outside the cluster.
|
||||
|
||||
# Add a Kubernetes Gateway that Points to the Istio Gateway
|
||||
|
||||
To allow traffic to reach Ingress, you will also need to provide a Kubernetes gateway resource in your YAML that points to Istio's implementation of the ingress gateway to the cluster.
|
||||
|
||||
1. Go to the namespace where you want to deploy the Kubernetes gateway and click **Import YAML.**
|
||||
1. Upload the gateway YAML as a file or paste it into the form. An example gateway YAML is provided below.
|
||||
1. Click **Import.**
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: Gateway
|
||||
metadata:
|
||||
name: bookinfo-gateway
|
||||
spec:
|
||||
selector:
|
||||
istio: ingressgateway # use istio default controller
|
||||
servers:
|
||||
- port:
|
||||
number: 80
|
||||
name: http
|
||||
protocol: HTTP
|
||||
hosts:
|
||||
- "*"
|
||||
---
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: VirtualService
|
||||
metadata:
|
||||
name: bookinfo
|
||||
spec:
|
||||
hosts:
|
||||
- "*"
|
||||
gateways:
|
||||
- bookinfo-gateway
|
||||
http:
|
||||
- match:
|
||||
- uri:
|
||||
exact: /productpage
|
||||
- uri:
|
||||
prefix: /static
|
||||
- uri:
|
||||
exact: /login
|
||||
- uri:
|
||||
exact: /logout
|
||||
- uri:
|
||||
prefix: /api/v1/products
|
||||
route:
|
||||
- destination:
|
||||
host: productpage
|
||||
port:
|
||||
number: 9080
|
||||
```
|
||||
|
||||
**Result:** You have configured your gateway resource so that Istio can receive traffic from outside the cluster.
|
||||
|
||||
Confirm that the resource exists by running:
|
||||
```
|
||||
kubectl get gateway -A
|
||||
```
|
||||
|
||||
The result should be something like this:
|
||||
```
|
||||
NAME AGE
|
||||
bookinfo-gateway 64m
|
||||
```
|
||||
|
||||
### Access the ProductPage Service from a Web Browser
|
||||
|
||||
To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:
|
||||
|
||||
`http://<IP of Istio controller>:<Port of istio controller>/productpage`
|
||||
|
||||
To get the ingress gateway URL and port,
|
||||
|
||||
1. Go to the `System` project in your cluster.
|
||||
1. Within the `System` project, go to `Resources` > `Workloads` then scroll down to the `istio-system` namespace.
|
||||
1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Under the name of this workload, you should see links, such as `80/tcp`.
|
||||
1. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append `/productpage` to the URL.
|
||||
|
||||
**Result:** You should see the BookInfo app in the web browser.
|
||||
|
||||
For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests.
|
||||
|
||||
### Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller
|
||||
|
||||
You can try the steps in this section to make sure the Kubernetes gateway is configured properly.
|
||||
|
||||
In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is `istio` and the value is `ingressgateway`. To make sure the label is appropriate for the gateway, do the following:
|
||||
|
||||
1. Go to the `System` project in your cluster.
|
||||
1. Within the `System` project, go to the namespace `istio-system`.
|
||||
1. Within `istio-system`, there is a workload named `istio-ingressgateway`.
|
||||
1. Click the name of this workload and go to the **Labels and Annotations** section. You should see that it has the key `istio` and the value `ingressgateway`. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.
|
||||
|
||||
### [Next: Set up Istio's Components for Traffic Management](set-up-traffic-management.md)
|
||||
+66
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 6. Set up Istio's Components for Traffic Management
|
||||
weight: 6
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/set-up-traffic-management
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/set-up-traffic-management
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/set-up-traffic-management
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/set-up-traffic-management/
|
||||
---
|
||||
|
||||
A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are *virtual services* and *destination rules*.
|
||||
|
||||
- [Virtual services](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/) intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
|
||||
- [Destination rules](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule/) serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.
|
||||
|
||||
This section describes how to add an example virtual service that corresponds to the `reviews` microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the `reviews` service.
|
||||
|
||||
In this example, we take the traffic to the `reviews` service and intercept it so that 50 percent of it goes to `v1` of the service and 50 percent goes to `v2`.
|
||||
|
||||
After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.
|
||||
|
||||
To deploy the virtual service and destination rules for the `reviews` service,
|
||||
|
||||
1. Go to the project view and click **Import YAML.**
|
||||
1. Copy resources below into the form.
|
||||
1. Click **Import.**
|
||||
|
||||
```
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: VirtualService
|
||||
metadata:
|
||||
name: reviews
|
||||
spec:
|
||||
hosts:
|
||||
- reviews
|
||||
http:
|
||||
- route:
|
||||
- destination:
|
||||
host: reviews
|
||||
subset: v1
|
||||
weight: 50
|
||||
- destination:
|
||||
host: reviews
|
||||
subset: v3
|
||||
weight: 50
|
||||
---
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: DestinationRule
|
||||
metadata:
|
||||
name: reviews
|
||||
spec:
|
||||
host: reviews
|
||||
subsets:
|
||||
- name: v1
|
||||
labels:
|
||||
version: v1
|
||||
- name: v2
|
||||
labels:
|
||||
version: v2
|
||||
- name: v3
|
||||
labels:
|
||||
version: v3
|
||||
```
|
||||
**Result:** When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the `reviews` service is divided evenly between `v1` and `v3`.
|
||||
|
||||
### [Next: Generate and View Traffic](generate-and-view-traffic.md)
|
||||
+327
@@ -0,0 +1,327 @@
|
||||
---
|
||||
title: 4. Add Deployments and Services with the Istio Sidecar
|
||||
weight: 4
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/tools/istio/setup/deploy-workloads
|
||||
- /rancher/v2.0-v2.4/en/istio/legacy/setup/deploy-workloads
|
||||
- /rancher/v2.0-v2.4/en/istio/v2.3.x-v2.4.x/setup/deploy-workloads
|
||||
- /rancher/v2.x/en/istio/v2.3.x-v2.4.x/setup/deploy-workloads/
|
||||
---
|
||||
|
||||
> **Prerequisite:** To enable Istio for a workload, the cluster and namespace must have Istio enabled.
|
||||
|
||||
Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.
|
||||
|
||||
To inject the Istio sidecar on an existing workload in the namespace, go to the workload, click the **⋮,** and click **Redeploy.** When the workload is redeployed, it will have the Envoy sidecar automatically injected.
|
||||
|
||||
Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see istio-init and istio-proxy alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.
|
||||
|
||||
### 3. Add Deployments and Services
|
||||
|
||||
Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.
|
||||
|
||||
1. Go to the project inside the cluster you want to deploy the workload on.
|
||||
1. In Workloads, click **Import YAML.**
|
||||
1. Copy the below resources into the form.
|
||||
1. Click **Import.**
|
||||
|
||||
This will set up the following sample resources from Istio's example BookInfo app:
|
||||
|
||||
Details service and deployment:
|
||||
|
||||
- A `details` Service
|
||||
- A ServiceAccount for `bookinfo-details`
|
||||
- A `details-v1` Deployment
|
||||
|
||||
Ratings service and deployment:
|
||||
|
||||
- A `ratings` Service
|
||||
- A ServiceAccount for `bookinfo-ratings`
|
||||
- A `ratings-v1` Deployment
|
||||
|
||||
Reviews service and deployments (three versions):
|
||||
|
||||
- A `reviews` Service
|
||||
- A ServiceAccount for `bookinfo-reviews`
|
||||
- A `reviews-v1` Deployment
|
||||
- A `reviews-v2` Deployment
|
||||
- A `reviews-v3` Deployment
|
||||
|
||||
Productpage service and deployment:
|
||||
|
||||
This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.
|
||||
|
||||
- A `productpage` service
|
||||
- A ServiceAccount for `bookinfo-productpage`
|
||||
- A `productpage-v1` Deployment
|
||||
|
||||
### Resource YAML
|
||||
|
||||
```yaml
|
||||
# Copyright 2017 Istio Authors
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
##################################################################################################
|
||||
# Details service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: details
|
||||
labels:
|
||||
app: details
|
||||
service: details
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: details
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-details
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: details-v1
|
||||
labels:
|
||||
app: details
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: details
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: details
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-details
|
||||
containers:
|
||||
- name: details
|
||||
image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Ratings service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: ratings
|
||||
labels:
|
||||
app: ratings
|
||||
service: ratings
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: ratings
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-ratings
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: ratings-v1
|
||||
labels:
|
||||
app: ratings
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: ratings
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: ratings
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-ratings
|
||||
containers:
|
||||
- name: ratings
|
||||
image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Reviews service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: reviews
|
||||
labels:
|
||||
app: reviews
|
||||
service: reviews
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: reviews
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-reviews
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v1
|
||||
labels:
|
||||
app: reviews
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v2
|
||||
labels:
|
||||
app: reviews
|
||||
version: v2
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v2
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v2
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v3
|
||||
labels:
|
||||
app: reviews
|
||||
version: v3
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v3
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v3
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Productpage services
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: productpage
|
||||
labels:
|
||||
app: productpage
|
||||
service: productpage
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: productpage
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-productpage
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: productpage-v1
|
||||
labels:
|
||||
app: productpage
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: productpage
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: productpage
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-productpage
|
||||
containers:
|
||||
- name: productpage
|
||||
image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
```
|
||||
|
||||
### [Next: Set up the Istio Gateway](set-up-istio-gateway.md)
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Adding Users to Clusters
|
||||
weight: 2020
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/clusters/adding-managing-cluster-members/
|
||||
- /rancher/v2.0-v2.4/en/k8s-in-rancher/cluster-members/
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/cluster-members
|
||||
---
|
||||
|
||||
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](k8s-in-rancher/projects-and-namespaces/project-members/) instead.
|
||||
|
||||
There are two contexts where you can add cluster members:
|
||||
|
||||
- Adding Members to a New Cluster
|
||||
|
||||
You can add members to a cluster as you create it (recommended if possible).
|
||||
|
||||
- [Adding Members to an Existing Cluster](#editing-cluster-membership)
|
||||
|
||||
You can always add members to a cluster after a cluster is provisioned.
|
||||
|
||||
## Editing Cluster Membership
|
||||
|
||||
Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.
|
||||
|
||||
1. From the **Global** view, open the cluster that you want to add members to.
|
||||
|
||||
2. From the main menu, select **Members**. Then click **Add Member**.
|
||||
|
||||
3. Search for the user or group that you want to add to the cluster.
|
||||
|
||||
If external authentication is configured:
|
||||
|
||||
- Rancher returns users from your [external authentication](../../../../pages-for-subheaders/about-authentication.md) 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](../../authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.md).
|
||||
|
||||
- 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](../../../../pages-for-subheaders/about-authentication.md#external-authentication-configuration-and-principal-users).
|
||||
|
||||
4. Assign the user or group **Cluster** roles.
|
||||
|
||||
[What are Cluster Roles?](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
|
||||
|
||||
>**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](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md).
|
||||
> - To remove roles from the list, [Lock/Unlock Roles](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md).
|
||||
|
||||
**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.
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
---
|
||||
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.](use-kubectl-and-kubeconfig.md#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.
|
||||
|
||||
_Available as of v2.4.6_
|
||||
|
||||
If admins have [enforced TTL on kubeconfig tokens](../../../../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires [rancher cli](cluster-admin/cluster-access/cli) to be present in your PATH.
|
||||
|
||||
|
||||
### Two Authentication Methods for RKE Clusters
|
||||
|
||||
If the cluster is not an [RKE cluster,](../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) 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.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster)
|
||||
|
||||
These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../pages-for-subheaders/rancher-manager-architecture.md#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,](../../../../pages-for-subheaders/rancher-manager-architecture.md#4-authorized-cluster-endpoint) which is only available for [RKE clusters.](../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook.
|
||||
|
||||
During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens.
|
||||
|
||||
The scheduling rules for `kube-api-auth` are listed below:
|
||||
|
||||
_Applies to v2.3.0 and higher_
|
||||
|
||||
| Component | nodeAffinity nodeSelectorTerms | nodeSelector | Tolerations |
|
||||
| -------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
|
||||
| kube-api-auth | `beta.kubernetes.io/os:NotIn:windows`<br/>`node-role.kubernetes.io/controlplane:In:"true"` | none | `operator:Exists` |
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
---
|
||||
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
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/k8s-in-rancher/kubectl/
|
||||
- /rancher/v2.0-v2.4/en/cluster-admin/kubectl
|
||||
- /rancher/v2.0-v2.4/en/concepts/clusters/kubeconfig-files/
|
||||
- /rancher/v2.0-v2.4/en/k8s-in-rancher/kubeconfig/
|
||||
- /rancher/2.x/en/cluster-admin/kubeconfig
|
||||
---
|
||||
|
||||
This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.
|
||||
|
||||
For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/).
|
||||
|
||||
- [Accessing clusters with kubectl shell in the Rancher UI](#accessing-clusters-with-kubectl-shell-in-the-rancher-ui)
|
||||
- [Accessing clusters with kubectl from your workstation](#accessing-clusters-with-kubectl-from-your-workstation)
|
||||
- [Note on Resources created using kubectl](#note-on-resources-created-using-kubectl)
|
||||
- [Authenticating Directly with a Downstream Cluster](#authenticating-directly-with-a-downstream-cluster)
|
||||
- [Connecting Directly to Clusters with FQDN Defined](#connecting-directly-to-clusters-with-fqdn-defined)
|
||||
- [Connecting Directly to Clusters without FQDN Defined](#connecting-directly-to-clusters-without-fqdn-defined)
|
||||
|
||||
|
||||
### Accessing Clusters with kubectl Shell in the Rancher UI
|
||||
|
||||
You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.
|
||||
|
||||
1. From the **Global** view, open the cluster that you want to access with kubectl.
|
||||
|
||||
2. Click **Launch kubectl**. Use the window that opens to interact with your Kubernetes cluster.
|
||||
|
||||
### Accessing Clusters with kubectl from Your Workstation
|
||||
|
||||
This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.
|
||||
|
||||
This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.
|
||||
|
||||
> **Prerequisites:** These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
|
||||
1. Log into Rancher. From the **Global** view, open the cluster that you want to access with kubectl.
|
||||
1. Click **Kubeconfig File**.
|
||||
1. Copy the contents displayed to your clipboard.
|
||||
1. Paste the contents into a new file on your local computer. Move the file to `~/.kube/config`. Note: The default location that kubectl uses for the kubeconfig file is `~/.kube/config`, but you can use any directory and specify it using the `--kubeconfig` flag, as in this command:
|
||||
```
|
||||
kubectl --kubeconfig /custom/path/kube.config get pods
|
||||
```
|
||||
1. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.
|
||||
|
||||
|
||||
### Note on Resources Created Using kubectl
|
||||
|
||||
Rancher will discover and show resources created by `kubectl`. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.
|
||||
|
||||
# Authenticating Directly with a Downstream Cluster
|
||||
|
||||
This section intended to help you set up an alternative method to access an [RKE cluster.](../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md)
|
||||
|
||||
This method is only available for RKE clusters that have the [authorized cluster endpoint](../../../../pages-for-subheaders/rancher-manager-architecture.md#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.](authorized-cluster-endpoint.md)
|
||||
|
||||
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.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#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
|
||||
```
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Adding a Pod Security Policy
|
||||
weight: 80
|
||||
---
|
||||
|
||||
> **Prerequisite:** The options below are available only for clusters that are [launched using RKE.](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md)
|
||||
|
||||
When your cluster is running pods with security-sensitive configurations, assign it a [pod security policy](../authentication-permissions-and-global-configuration/create-pod-security-policies.md), 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. From the **Global** view, find the cluster to which you want to apply a pod security policy. Select **⋮ > Edit**.
|
||||
|
||||
2. Expand **Cluster Options**.
|
||||
|
||||
3. From **Pod Security Policy Support**, select **Enabled**.
|
||||
|
||||
>**Note:** This option is only available for clusters [provisioned by RKE](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md).
|
||||
|
||||
4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster.
|
||||
|
||||
Rancher ships with [policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md#default-pod-security-policies) of `restricted` and `unrestricted`, although you can [create custom policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md#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.
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
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](../authentication-permissions-and-global-configuration/create-pod-security-policies.md).
|
||||
>**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.
|
||||
+225
@@ -0,0 +1,225 @@
|
||||
---
|
||||
title: Backing up a Cluster
|
||||
weight: 2045
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) can be easily performed.
|
||||
|
||||
Rancher recommends configuring recurrent `etcd` snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.
|
||||
|
||||
Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [How snapshots work](#how-snapshots-work)
|
||||
- [Configuring recurring snapshots](#configuring-recurring-snapshots)
|
||||
- [One-time snapshots](#one-time-snapshots)
|
||||
- [Snapshot backup targets](#snapshot-backup-targets)
|
||||
- [Local backup target](#local-backup-target)
|
||||
- [S3 backup target](#s3-backup-target)
|
||||
- [Using a custom CA certificate for S3](#using-a-custom-ca-certificate-for-s3)
|
||||
- [IAM Support for storing snapshots in S3](#iam-support-for-storing-snapshots-in-s3)
|
||||
- [Viewing available snapshots](#viewing-available-snapshots)
|
||||
- [Safe timestamps](#safe-timestamps)
|
||||
- [Enabling snapshot features for clusters created before Rancher v2.2.0](#enabling-snapshot-features-for-clusters-created-before-rancher-v2-2-0)
|
||||
|
||||
# How Snapshots Work
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.4.0+">
|
||||
|
||||
### 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.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.4.0">
|
||||
|
||||
When Rancher creates a snapshot, only the etcd data is included in the snapshot.
|
||||
|
||||
Because the Kubernetes version is not included in the snapshot, there is no option to restore a cluster to a different Kubernetes version.
|
||||
|
||||
It's always recommended to take a new snapshot before any upgrades.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
# Configuring Recurring Snapshots
|
||||
|
||||
Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.
|
||||
|
||||
By default, [Rancher launched Kubernetes clusters](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) 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 **Global** view, navigate to the cluster that you want to take a one-time snapshot.
|
||||
|
||||
2. Click the **⋮ > Snapshot Now**.
|
||||
|
||||
**Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target.
|
||||
|
||||
# Snapshot Backup Targets
|
||||
|
||||
Rancher supports two different backup targets:
|
||||
|
||||
* [Local Target](#local-backup-target)
|
||||
* [S3 Target](#s3-backup-target)
|
||||
|
||||
### Local Backup Target
|
||||
|
||||
By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) in `/opt/rke/etcd-snapshots`. All recurring snapshots are taken at configured intervals. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster.
|
||||
|
||||
### S3 Backup Target
|
||||
|
||||
The `S3` backup target allows users to configure a S3 compatible backend to store the snapshots. The primary benefit of this option is that if the cluster loses all the etcd nodes, the cluster can still be restored as the snapshots are stored externally. Rancher recommends external targets like `S3` backup, however its configuration requirements do require additional effort that should be considered.
|
||||
|
||||
| Option | Description | Required|
|
||||
|---|---|---|
|
||||
|S3 Bucket Name| S3 bucket name where backups will be stored| *|
|
||||
|S3 Region|S3 region for the backup bucket| |
|
||||
|S3 Region Endpoint|S3 regions endpoint for the backup bucket|* |
|
||||
|S3 Access Key|S3 access key with permission to access the backup bucket|*|
|
||||
|S3 Secret Key|S3 secret key with permission to access the backup bucket|*|
|
||||
| Custom CA Certificate | A custom certificate used to access private S3 backends _Available as of v2.2.5_ ||
|
||||
|
||||
### Using a custom CA certificate for S3
|
||||
|
||||
_Available as of v2.2.5_
|
||||
|
||||
The backup snapshot can be stored on a custom `S3` backup like [minio](https://min.io/). If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the `Custom CA Certificate` option to connect to the S3 backend.
|
||||
|
||||
### IAM Support for Storing Snapshots in S3
|
||||
|
||||
The `S3` backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:
|
||||
|
||||
- The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.
|
||||
- The cluster etcd nodes must have network access to the specified S3 endpoint.
|
||||
- The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket.
|
||||
- The Rancher Server worker node(s) must have network access to the specified S3 endpoint.
|
||||
|
||||
To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)
|
||||
|
||||
# Viewing Available Snapshots
|
||||
|
||||
The list of all available snapshots for the cluster is available in the Rancher UI.
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to view snapshots.
|
||||
|
||||
2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
|
||||
|
||||
# Safe Timestamps
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
As of v2.2.6, snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. As of Rancher v2.3.0, the option `safe_timestamp` is added to support compatible file names. When this flag is set to `true`, all special characters in the snapshot filename timestamp are replaced.
|
||||
|
||||
This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface.
|
||||
|
||||
# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0
|
||||
|
||||
If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) 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](restoring-etcd.md).
|
||||
+284
@@ -0,0 +1,284 @@
|
||||
---
|
||||
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] | [Imported Nodes][4] |
|
||||
| ------------------------------------------------------------------------------ | --------------- | ----------------- | ------------------- | ------------------- |
|
||||
| The Rancher deployment namespace (`cattle-system` by default) | ✓ | ✓ | ✓ | ✓ |
|
||||
| `serviceAccount`, `clusterRoles`, and `clusterRoleBindings` labeled by Rancher | ✓ | ✓ | ✓ | ✓ |
|
||||
| Labels, Annotations, and Finalizers | ✓ | ✓ | ✓ | ✓ |
|
||||
| Rancher Deployment | ✓ | ✓ | ✓ | |
|
||||
| Machines, clusters, projects, and user custom resource definitions (CRDs) | ✓ | ✓ | ✓ | |
|
||||
| All resources create under the `management.cattle.io` API Group | ✓ | ✓ | ✓ | |
|
||||
| All CRDs created by Rancher v2.x | ✓ | ✓ | ✓ | |
|
||||
|
||||
[1]: cluster-provisioning/rke-clusters/node-pools/
|
||||
[2]: cluster-provisioning/rke-clusters/custom-nodes/
|
||||
[3]: cluster-provisioning/hosted-kubernetes-clusters/
|
||||
[4]: cluster-provisioning/imported-clusters/
|
||||
|
||||
## Removing a Node from a Cluster by Rancher UI
|
||||
|
||||
When the node is in `Active` state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed.
|
||||
|
||||
**To restart a node:**
|
||||
|
||||
```
|
||||
# using reboot
|
||||
$ sudo reboot
|
||||
|
||||
# using shutdown
|
||||
$ sudo shutdown -r now
|
||||
```
|
||||
|
||||
## Removing Rancher Components from a Cluster Manually
|
||||
|
||||
When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components.
|
||||
|
||||
>**Warning:** The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost.
|
||||
|
||||
### Removing Rancher Components from Imported Clusters
|
||||
|
||||
For imported clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions.
|
||||
|
||||
After the imported cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was imported into Rancher.
|
||||
|
||||
<Tabs>
|
||||
<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 an imported cluster using the Rancher UI (or API), the following events occur.
|
||||
|
||||
1. Rancher creates a `serviceAccount` that it uses to remove the Rancher components from the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the Rancher components.
|
||||
|
||||
1. Using the `serviceAccount`, Rancher schedules and runs a [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) that cleans the Rancher components off of the cluster. This job also references the `serviceAccount` and its roles as dependencies, so the job deletes them before its completion.
|
||||
|
||||
1. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes.
|
||||
|
||||
**Result:** All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="By Script">
|
||||
|
||||
Rather than cleaning imported cluster nodes using the Rancher UI, you can run a script instead. This functionality is available since `v2.1.0`.
|
||||
|
||||
>**Prerequisite:**
|
||||
>
|
||||
>Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
|
||||
1. Open a web browser, navigate to [GitHub](https://github.com/rancher/rancher/blob/master/cleanup/user-cluster.sh), and download `user-cluster.sh`.
|
||||
|
||||
1. Make the script executable by running the following command from the same directory as `user-cluster.sh`:
|
||||
|
||||
```
|
||||
chmod +x user-cluster.sh
|
||||
```
|
||||
|
||||
1. **Air Gap Environments Only:** Open `user-cluster.sh` and replace `yaml_url` with the URL in `user-cluster.yml`.
|
||||
|
||||
If you don't have an air gap environment, skip this step.
|
||||
|
||||
1. From the same directory, run the script and provide the `rancher/rancher-agent` image version which should be equal to the version of Rancher used to manage the cluster. (`<RANCHER_VERSION>`):
|
||||
|
||||
>**Tip:**
|
||||
>
|
||||
>Add the `-dry-run` flag to preview the script's outcome without making changes.
|
||||
```
|
||||
./user-cluster.sh rancher/rancher-agent:<RANCHER_VERSION>
|
||||
```
|
||||
|
||||
**Result:** The script runs. All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted.
|
||||
|
||||
</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
|
||||
```
|
||||
+101
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Cloning Clusters
|
||||
weight: 2035
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/cluster-provisioning/cloning-clusters/
|
||||
---
|
||||
|
||||
If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster.
|
||||
|
||||
Duplication of imported clusters is not supported.
|
||||
|
||||
| Cluster Type | Cloneable? |
|
||||
|----------------------------------|---------------|
|
||||
| [Nodes Hosted by Infrastructure Provider](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md) | ✓ |
|
||||
| [Hosted Kubernetes Providers](../../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md) | ✓ |
|
||||
| [Custom Cluster](../../../pages-for-subheaders/use-existing-nodes.md) | ✓ |
|
||||
| [Imported Cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md) | |
|
||||
|
||||
> **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](../../../pages-for-subheaders/cli-with-rancher.md). Remember to [create an API bearer token](../../../reference-guides/user-settings/api-keys.md) if necessary.
|
||||
|
||||
|
||||
## 1. Export Cluster Config
|
||||
|
||||
Begin by using Rancher CLI to export the configuration for the cluster that you want to clone.
|
||||
|
||||
1. Open Terminal and change your directory to the location of the Rancher CLI binary, `rancher`.
|
||||
|
||||
1. Enter the following command to list the clusters managed by Rancher.
|
||||
|
||||
|
||||
./rancher cluster ls
|
||||
|
||||
|
||||
1. Find the cluster that you want to clone, and copy either its resource `ID` or `NAME` to your clipboard. From this point on, we'll refer to the resource `ID` or `NAME` as `<RESOURCE_ID>`, which is used as a placeholder in the next step.
|
||||
|
||||
1. Enter the following command to export the configuration for your cluster.
|
||||
|
||||
|
||||
./rancher clusters export <RESOURCE_ID>
|
||||
|
||||
|
||||
**Step Result:** The YAML for a cloned cluster prints to Terminal.
|
||||
|
||||
1. Copy the YAML to your clipboard and paste it in a new file. Save the file as `cluster-template.yml` (or any other name, as long as it has a `.yml` extension).
|
||||
|
||||
## 2. Modify Cluster Config
|
||||
|
||||
Use your favorite text editor to modify the cluster configuration in `cluster-template.yml` for your cloned cluster.
|
||||
|
||||
> **Note:** As of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#config-file-structure-in-rancher-v2-3-0)
|
||||
|
||||
1. Open `cluster-template.yml` (or whatever you named your config) in your favorite text editor.
|
||||
|
||||
>**Warning:** Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.
|
||||
|
||||
|
||||
1. As depicted in the example below, at the `<CLUSTER_NAME>` placeholder, replace your original cluster's name with a unique name (`<CLUSTER_NAME>`). If your cloned cluster has a duplicate name, the cluster will not provision successfully.
|
||||
|
||||
```yml
|
||||
Version: v3
|
||||
clusters:
|
||||
<CLUSTER_NAME>: # ENTER UNIQUE NAME
|
||||
dockerRootDir: /var/lib/docker
|
||||
enableNetworkPolicy: false
|
||||
rancherKubernetesEngineConfig:
|
||||
addonJobTimeout: 30
|
||||
authentication:
|
||||
strategy: x509
|
||||
authorization: {}
|
||||
bastionHost: {}
|
||||
cloudProvider: {}
|
||||
ignoreDockerVersion: true
|
||||
```
|
||||
|
||||
1. For each `nodePools` section, replace the original nodepool name with a unique name at the `<NODEPOOL_NAME>` placeholder. If your cloned cluster has a duplicate nodepool name, the cluster will not provision successfully.
|
||||
|
||||
```yml
|
||||
nodePools:
|
||||
<NODEPOOL_NAME>:
|
||||
clusterId: do
|
||||
controlPlane: true
|
||||
etcd: true
|
||||
hostnamePrefix: mark-do
|
||||
nodeTemplateId: do
|
||||
quantity: 1
|
||||
worker: true
|
||||
```
|
||||
|
||||
1. When you're done, save and close the configuration.
|
||||
|
||||
## 3. Launch Cloned Cluster
|
||||
|
||||
Move `cluster-template.yml` into the same directory as the Rancher CLI binary. Then run this command:
|
||||
|
||||
./rancher up --file cluster-template.yml
|
||||
|
||||
**Result:** Your cloned cluster begins provisioning. Enter `./rancher cluster ls` to confirm. You can also log into the Rancher UI and open the **Global** view to watch your provisioning cluster's progress.
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: GlusterFS Volumes
|
||||
weight: 5000
|
||||
---
|
||||
|
||||
> This section only applies to [RKE clusters.](../../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md)
|
||||
|
||||
In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. The logging of the `kubelet` will show: `transport endpoint is not connected`. To prevent this from happening, you can configure your cluster to mount the `systemd-run` binary in the `kubelet` container. There are two requirements before you can change the cluster configuration:
|
||||
|
||||
- The node needs to have the `systemd-run` binary installed (this can be checked by using the command `which systemd-run` on each cluster node)
|
||||
- The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use)
|
||||
|
||||
```
|
||||
docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version
|
||||
```
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
|
||||
|
||||
```
|
||||
services:
|
||||
kubelet:
|
||||
extra_binds:
|
||||
- "/usr/bin/systemd-run:/usr/bin/systemd-run"
|
||||
```
|
||||
|
||||
After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline:
|
||||
|
||||
```
|
||||
Detected OS with systemd
|
||||
```
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: How Persistent Storage Works
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/workloads/add-persistent-volume-claim
|
||||
---
|
||||
|
||||
A persistent volume (PV) is a piece of storage in the Kubernetes cluster, while a persistent volume claim (PVC) is a request for storage.
|
||||
|
||||
There are two ways to use persistent storage in Kubernetes:
|
||||
|
||||
- Use an existing persistent volume
|
||||
- Dynamically provision new persistent volumes
|
||||
|
||||
To use an existing PV, your application will need to use a PVC that is bound to a PV, and the PV should include the minimum resources that the PVC requires.
|
||||
|
||||
For dynamic storage provisioning, your application will need to use a PVC that is bound to a storage class. The storage class contains the authorization to provision new persistent volumes.
|
||||
|
||||
|
||||
|
||||
For more information, refer to the [official Kubernetes documentation on storage](https://kubernetes.io/docs/concepts/storage/volumes/)
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [About persistent volume claims](#about-persistent-volume-claims)
|
||||
- [PVCs are required for both new and existing persistent storage](#pvcs-are-required-for-both-new-and-existing-persistent-storage)
|
||||
- [Setting up existing storage with a PVC and PV](#setting-up-existing-storage-with-a-pvc-and-pv)
|
||||
- [Binding PVs to PVCs](#binding-pvs-to-pvcs)
|
||||
- [Provisioning new storage with a PVC and storage class](#provisioning-new-storage-with-a-pvc-and-storage-class)
|
||||
|
||||
# About Persistent Volume Claims
|
||||
|
||||
Persistent volume claims (PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. A PVC is mounted into a workloads as a volume so that the workload can claim its specified share of the persistent storage.
|
||||
|
||||
To access persistent storage, a pod must have a PVC mounted as a volume. This PVC lets your deployment application store its data in an external location, so that if a pod fails, it can be replaced with a new pod and continue accessing its data stored externally, as though an outage never occurred.
|
||||
|
||||
Each Rancher project contains a list of PVCs that you've created, available from **Resources > Workloads > Volumes.** (In versions before v2.3.0, the PVCs are in the **Volumes** tab.) You can reuse these PVCs when creating deployments in the future.
|
||||
|
||||
### PVCs are Required for Both New and Existing Persistent Storage
|
||||
|
||||
A PVC is required for pods to use any persistent storage, regardless of whether the workload is intended to use storage that already exists, or the workload will need to dynamically provision new storage on demand.
|
||||
|
||||
If you are setting up existing storage for a workload, the workload mounts a PVC, which refers to a PV, which corresponds to existing storage infrastructure.
|
||||
|
||||
If a workload should request new storage, the workload mounts PVC, which refers to a storage class, which has the capability to create a new PV along with its underlying storage infrastructure.
|
||||
|
||||
Rancher lets you create as many PVCs within a project as you'd like.
|
||||
|
||||
You can mount PVCs to a deployment as you create it, or later, after the deployment is running.
|
||||
|
||||
# Setting up Existing Storage with a PVC and PV
|
||||
|
||||
Your pods can store data in [volumes,](https://kubernetes.io/docs/concepts/storage/volumes/) but if the pod fails, that data is lost. To solve this issue, Kubernetes offers persistent volumes (PVs), which are Kubernetes resources that correspond to external storage disks or file systems that your pods can access. If a pod crashes, its replacement pod can access the data in persistent storage without any data loss.
|
||||
|
||||
PVs can represent a physical disk or file system that you host on premise, or a vendor-hosted storage resource, such as Amazon EBS or Azure Disk.
|
||||
|
||||
Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.
|
||||
|
||||
> **Important:** PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.
|
||||
|
||||
### Binding PVs to PVCs
|
||||
|
||||
When pods are set up to use persistent storage, they mount a persistent volume claim (PVC) that is mounted the same way as any other Kubernetes volume. When each PVC is created, the Kubernetes master considers it to be a request for storage and binds it to a PV that matches the minimum resource requirements of the PVC. Not every PVC is guaranteed to be bound to a PV. According to the Kubernetes [documentation,](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)
|
||||
|
||||
> Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.
|
||||
|
||||
In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PVs that has at least the amount of disk space required by the PVC.
|
||||
|
||||
To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume.
|
||||
|
||||
# Provisioning New Storage with a PVC and Storage Class
|
||||
|
||||
Storage Classes allow you to create PVs dynamically without having to create persistent storage in an infrastructure provider first.
|
||||
|
||||
For example, if a workload is bound to a PVC and the PVC refers to an Amazon EBS Storage Class, the storage class can dynamically create an EBS volume and a corresponding PV.
|
||||
|
||||
The Kubernetes master will then bind the newly created PV to your workload's PVC, allowing your workload to use the persistent storage.
|
||||
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Dynamically Provisioning New Storage in Rancher
|
||||
weight: 2
|
||||
---
|
||||
|
||||
This section describes how to provision new persistent storage for workloads in Rancher.
|
||||
|
||||
This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on [how storage works.](about-persistent-storage.md)
|
||||
|
||||
New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud.
|
||||
|
||||
If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster.
|
||||
|
||||
To provision new storage for your workloads, follow these steps:
|
||||
|
||||
1. [Add a storage class and configure it to use your storage.](#1-add-a-storage-class-and-configure-it-to-use-your-storage)
|
||||
2. [Add a persistent volume claim that refers to the storage class.](#2-add-a-persistent-volume-claim-that-refers-to-the-storage-class)
|
||||
3. [Mount the persistent volume claim as a volume for your workload.](#3-mount-the-persistent-volume-claim-as-a-volume-for-your-workload)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- To set up persistent storage, the `Manage Volumes` [role](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-role-reference) is required.
|
||||
- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.
|
||||
- The cloud provider must be enabled. For details on enabling cloud providers, refer to [this page.](cluster-provisioning/rke-clusters/options/cloud-providers/)
|
||||
- Make sure your storage provisioner is available to be enabled.
|
||||
|
||||
The following storage provisioners are enabled by default:
|
||||
|
||||
Name | Plugin
|
||||
--------|----------
|
||||
Amazon EBS Disk | `aws-ebs`
|
||||
AzureFile | `azure-file`
|
||||
AzureDisk | `azure-disk`
|
||||
Google Persistent Disk | `gce-pd`
|
||||
Longhorn | `flex-volume-longhorn`
|
||||
VMware vSphere Volume | `vsphere-volume`
|
||||
Local | `local`
|
||||
Network File System | `nfs`
|
||||
hostPath | `host-path`
|
||||
|
||||
To use a storage provisioner that is not on the above list, you will need to use a [feature flag to enable unsupported storage drivers.](installation/options/feature-flags/enable-not-default-storage-drivers/)
|
||||
|
||||
### 1. Add a storage class and configure it to use your storage
|
||||
|
||||
These steps describe how to set up a storage class at the cluster level.
|
||||
|
||||
1. Go to the cluster for which you want to dynamically provision persistent storage volumes.
|
||||
|
||||
1. From the cluster view, select `Storage > Storage Classes`. Click `Add Class`.
|
||||
|
||||
1. Enter a `Name` for your storage class.
|
||||
|
||||
1. From the `Provisioner` drop-down, select the service that you want to use to dynamically provision storage volumes. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, use the `Amazon EBS Disk` provisioner.
|
||||
|
||||
1. From the `Parameters` section, fill out the information required for the service to dynamically provision storage volumes. Each provisioner requires different information to dynamically provision storage volumes. Consult the service's documentation for help on how to obtain this information.
|
||||
|
||||
1. Click `Save`.
|
||||
|
||||
**Result:** The storage class is available to be consumed by a PVC.
|
||||
|
||||
For full information about the storage class parameters, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters).
|
||||
|
||||
### 2. Add a persistent volume claim that refers to the storage class
|
||||
|
||||
These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.
|
||||
|
||||
1. Go to the project containing a workload that you want to add a PVC to.
|
||||
|
||||
1. From the main navigation bar, choose **Resources > Workloads.** (In versions before v2.3.0, choose **Workloads** on the main navigation bar.) Then select the **Volumes** tab. Click **Add Volume**.
|
||||
|
||||
1. Enter a **Name** for the volume claim.
|
||||
|
||||
1. Select the namespace of the volume claim.
|
||||
|
||||
1. In the **Source** field, click **Use a Storage Class to provision a new persistent volume.**
|
||||
|
||||
1. Go to the **Storage Class** drop-down and select the storage class that you created.
|
||||
|
||||
1. Enter a volume **Capacity**.
|
||||
|
||||
1. Optional: Expand the **Customize** section and select the [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) that you want to use.
|
||||
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** Your PVC is created. You can now attach it to any workload in the project.
|
||||
|
||||
### 3. Mount the persistent volume claim as a volume for your workload
|
||||
|
||||
Mount PVCs to workloads so that your applications can store their data.
|
||||
|
||||
You can mount PVCs during the deployment of a workload, or following workload creation.
|
||||
|
||||
To attach the PVC to a new workload,
|
||||
|
||||
1. Create a workload as you would in [Deploying Workloads](../../../../new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md).
|
||||
1. For **Workload Type**, select **Stateful set of 1 pod**.
|
||||
1. Expand the **Volumes** section and click **Add Volume > Add a New Persistent Volume (Claim).**
|
||||
1. In the **Persistent Volume Claim** section, select the newly created persistent volume claim that is attached to the storage class.
|
||||
1. In the **Mount Point** field, enter the path that the workload will use to access the volume.
|
||||
1. Click **Launch.**
|
||||
|
||||
**Result:** When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.
|
||||
|
||||
To attach the PVC to an existing workload,
|
||||
|
||||
1. Go to the project that has the workload that will have the PVC attached.
|
||||
1. Go to the workload that will have persistent storage and click **⋮ > Edit.**
|
||||
1. Expand the **Volumes** section and click **Add Volume > Add a New Persistent Volume (Claim).**
|
||||
1. In the **Persistent Volume Claim** section, select the newly created persistent volume claim that is attached to the storage class.
|
||||
1. In the **Mount Point** field, enter the path that the workload will use to access the volume.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. If not, Rancher will provision new persistent storage.
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: iSCSI Volumes
|
||||
weight: 6000
|
||||
---
|
||||
|
||||
In [Rancher Launched Kubernetes clusters](../../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes.
|
||||
|
||||
Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the [iSCSI initiator tool](http://www.open-iscsi.com/), which is embedded in the kubelet's `rancher/hyperkube` Docker image. From each kubelet (i.e., the _initiator_), the tool discovers and launches sessions with an iSCSI volume (i.e., the _target_). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure.
|
||||
|
||||
If you encounter this issue, you can work around it by installing the initiator tool on each node in your cluster. You can install the iSCSI initiator tool by logging into your cluster nodes and entering one of the following commands:
|
||||
|
||||
| Platform | Package Name | Install Command |
|
||||
| ------------- | ----------------------- | -------------------------------------- |
|
||||
| Ubuntu/Debian | `open-iscsi` | `sudo apt install open-iscsi` |
|
||||
| RHEL | `iscsi-initiator-utils` | `yum install iscsi-initiator-utils -y` |
|
||||
|
||||
|
||||
After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
|
||||
|
||||
```
|
||||
services:
|
||||
kubelet:
|
||||
extra_binds:
|
||||
- "/etc/iscsi:/etc/iscsi"
|
||||
- "/sbin/iscsiadm:/sbin/iscsiadm"
|
||||
```
|
||||
+104
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Setting up Existing Storage
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This section describes how to set up existing persistent storage for workloads in Rancher.
|
||||
|
||||
> This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](about-persistent-storage.md)
|
||||
|
||||
To set up storage, follow these steps:
|
||||
|
||||
1. [Set up persistent storage.](#1-set-up-persistent-storage)
|
||||
2. [Add a persistent volume that refers to the persistent storage.](#2-add-a-persistent-volume-that-refers-to-the-persistent-storage)
|
||||
3. [Add a persistent volume claim that refers to the persistent volume.](#3-add-a-persistent-volume-claim-that-refers-to-the-persistent-volume)
|
||||
4. [Mount the persistent volume claim as a volume in your workload.](#4-mount-the-persistent-volume-claim-as-a-volume-in-your-workload)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- To create a persistent volume as a Kubernetes resource, you must have the `Manage Volumes` [role.](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-role-reference)
|
||||
- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.
|
||||
|
||||
### 1. Set up persistent storage
|
||||
|
||||
Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.
|
||||
|
||||
The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using [vSphere,](../provisioning-storage-examples/vsphere-storage.md) [NFS,](../provisioning-storage-examples/nfs-storage.md) or Amazon's [EBS.](../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md)
|
||||
|
||||
If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster.
|
||||
|
||||
### 2. Add a persistent volume that refers to the persistent storage
|
||||
|
||||
These steps describe how to set up a persistent volume at the cluster level in Kubernetes.
|
||||
|
||||
1. From the cluster view, select **Storage > Persistent Volumes**.
|
||||
|
||||
1. Click **Add Volume**.
|
||||
|
||||
1. Enter a **Name** for the persistent volume.
|
||||
|
||||
1. Select the **Volume Plugin** for the disk type or service that you're using. When adding storage to a cluster that's hosted by a cloud provider, use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the `Amazon EBS Disk` volume plugin.
|
||||
|
||||
1. Enter the **Capacity** of your volume in gigabytes.
|
||||
|
||||
1. Complete the **Plugin Configuration** form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation.
|
||||
|
||||
1. Optional: In the **Customize** form, configure the [access modes.](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) This options sets how many nodes can access the volume, along with the node read/write permissions. The [Kubernetes Documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) includes a table that lists which access modes are supported by the plugins available.
|
||||
|
||||
1. Optional: In the **Customize** form, configure the [mount options.](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options) Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin's vendor documentation for the mount options available.
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** Your new persistent volume is created.
|
||||
|
||||
### 3. Add a persistent volume claim that refers to the persistent volume
|
||||
|
||||
These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.
|
||||
|
||||
1. Go to the project containing a workload that you want to add a persistent volume claim to.
|
||||
|
||||
1. Then click the **Volumes** tab and click **Add Volume**. (In versions before v2.3.0, click **Workloads** on the main navigation bar, then **Volumes.**)
|
||||
|
||||
1. Enter a **Name** for the volume claim.
|
||||
|
||||
1. Select the namespace of the workload that you want to add the persistent storage to.
|
||||
|
||||
1. In the section called **Use an existing persistent volume,** go to the **Persistent Volume** drop-down and choose the persistent volume that you created.
|
||||
|
||||
1. **Optional:** From **Customize**, select the [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) that you want to use.
|
||||
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** Your PVC is created. You can now attach it to any workload in the project.
|
||||
|
||||
### 4. Mount the persistent volume claim as a volume in your workload
|
||||
|
||||
Mount PVCs to stateful workloads so that your applications can store their data.
|
||||
|
||||
You can mount PVCs during the deployment of a workload, or following workload creation.
|
||||
|
||||
The following steps describe how to assign existing storage to a new workload that is a stateful set:
|
||||
|
||||
1. From the **Project** view, go to the **Workloads** tab.
|
||||
1. Click **Deploy.**
|
||||
1. Enter a name for the workload.
|
||||
1. Next to the **Workload Type** field, click **More Options.**
|
||||
1. Click **Stateful set of 1 pod.** Optionally, configure the number of pods.
|
||||
1. Choose the namespace where the workload will be deployed.
|
||||
1. Expand the **Volumes** section and click **Add Volume > Use an existing persistent volume (claim).**.
|
||||
1. In the **Persistent Volume Claim** field, select the PVC that you created.
|
||||
1. In the **Mount Point** field, enter the path that the workload will use to access the volume.
|
||||
1. Click **Launch.**
|
||||
|
||||
**Result:** When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.
|
||||
|
||||
The following steps describe how to assign persistent storage to an existing workload:
|
||||
|
||||
1. From the **Project** view, go to the **Workloads** tab.
|
||||
1. Go to the workload that you want to add the persistent storage to. The workload type should be a stateful set. Click **⋮ > Edit.**
|
||||
1. Expand the **Volumes** section and click **Add Volume > Use an existing persistent volume (claim).**.
|
||||
1. In the **Persistent Volume Claim** field, select the PVC that you created.
|
||||
1. In the **Mount Point** field, enter the path that the workload will use to access the volume.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: NFS Storage
|
||||
weight: 3054
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/clusters/adding-storage/provisioning-storage/nfs/
|
||||
---
|
||||
|
||||
Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage](../../../../../pages-for-subheaders/create-kubernetes-persistent-storage.md).
|
||||
>
|
||||
>- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.
|
||||
|
||||
>**Recommended:** To simplify the process of managing firewall rules, use NFSv4.
|
||||
|
||||
1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage.
|
||||
|
||||
1. Enter the following command:
|
||||
|
||||
```
|
||||
sudo apt-get install nfs-kernel-server
|
||||
```
|
||||
|
||||
1. Enter the command below, which sets the directory used for storage, along with user access rights. Modify the command if you'd like to keep storage at a different directory.
|
||||
|
||||
```
|
||||
mkdir -p /nfs && chown nobody:nogroup /nfs
|
||||
```
|
||||
- The `-p /nfs` parameter creates a directory named `nfs` at root.
|
||||
- The `chown nobody:nogroup /nfs` parameter allows all access to the storage directory.
|
||||
|
||||
1. Create an NFS exports table. This table sets the directory paths on your NFS server that are exposed to the nodes that will use the server for storage.
|
||||
|
||||
1. Open `/etc/exports` using your text editor of choice.
|
||||
1. Add the path of the `/nfs` folder that you created in step 3, along with the IP addresses of your cluster nodes. Add an entry for each IP address in your cluster. Follow each address and its accompanying parameters with a single space that is a delimiter.
|
||||
|
||||
```
|
||||
/nfs <IP_ADDRESS1>(rw,sync,no_subtree_check) <IP_ADDRESS2>(rw,sync,no_subtree_check) <IP_ADDRESS3>(rw,sync,no_subtree_check)
|
||||
```
|
||||
|
||||
**Tip:** You can replace the IP addresses with a subnet. For example: `10.212.50.12/24`
|
||||
|
||||
1. Update the NFS table by entering the following command:
|
||||
|
||||
```
|
||||
exportfs -ra
|
||||
```
|
||||
|
||||
1. Open the ports used by NFS.
|
||||
|
||||
1. To find out what ports NFS is using, enter the following command:
|
||||
|
||||
```
|
||||
rpcinfo -p | grep nfs
|
||||
```
|
||||
2. [Open the ports](https://help.ubuntu.com/lts/serverguide/firewall.html.en) that the previous command outputs. For example, the following command opens port 2049:
|
||||
|
||||
```
|
||||
sudo ufw allow 2049
|
||||
```
|
||||
|
||||
**Result:** Your NFS server is configured to be used for storage with your Rancher nodes.
|
||||
|
||||
## What's Next?
|
||||
|
||||
Within Rancher, add the NFS server as a storage volume and/or storage class. After adding the server, you can use it for storage for your deployments.
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Creating Persistent Storage in Amazon's EBS
|
||||
weight: 3053
|
||||
---
|
||||
|
||||
This section describes how to set up Amazon's Elastic Block Store in EC2.
|
||||
|
||||
1. From the EC2 console, go to the **ELASTIC BLOCK STORE** section in the left panel and click **Volumes.**
|
||||
1. Click **Create Volume.**
|
||||
1. Optional: Configure the size of the volume or other options. The volume should be created in the same availability zone as the instance it will be attached to.
|
||||
1. Click **Create Volume.**
|
||||
1. Click **Close.**
|
||||
|
||||
**Result:** Persistent storage has been created.
|
||||
|
||||
For details on how to set up the newly created storage in Rancher, refer to the section on [setting up existing storage.](../manage-persistent-storage/set-up-existing-storage.md)
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: vSphere Storage
|
||||
weight: 3055
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/clusters/adding-storage/provisioning-storage/vsphere/
|
||||
---
|
||||
|
||||
To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a [persistent volume claim](k8s-in-rancher/volumes-and-storage/persistent-volume-claims/).
|
||||
|
||||
In order to dynamically provision storage in vSphere, the vSphere provider must be [enabled.](../../../../new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.md)
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Creating a StorageClass](#creating-a-storageclass)
|
||||
- [Creating a Workload with a vSphere Volume](#creating-a-workload-with-a-vsphere-volume)
|
||||
- [Verifying Persistence of the Volume](#verifying-persistence-of-the-volume)
|
||||
- [Why to Use StatefulSets Instead of Deployments](#why-to-use-statefulsets-instead-of-deployments)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
In order to provision vSphere volumes in a cluster created with the [Rancher Kubernetes Engine (RKE)](../../../../../pages-for-subheaders/launch-kubernetes-with-rancher.md), the [vSphere cloud provider](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/vsphere) must be explicitly enabled in the [cluster options](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md).
|
||||
|
||||
### Creating a StorageClass
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details.
|
||||
|
||||
1. From the Global view, open the cluster where you want to provide vSphere storage.
|
||||
2. From the main menu, select **Storage > Storage Classes**. Then click **Add Class**.
|
||||
3. Enter a **Name** for the class.
|
||||
4. Under **Provisioner**, select **VMWare vSphere Volume**.
|
||||
|
||||
|
||||
|
||||
5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/storageclass.html) for details.
|
||||
5. Click **Save**.
|
||||
|
||||
### Creating a Workload with a vSphere Volume
|
||||
|
||||
1. From the cluster where you configured vSphere storage, begin creating a workload as you would in [Deploying Workloads](../../../../new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md).
|
||||
2. For **Workload Type**, select **Stateful set of 1 pod**.
|
||||
3. Expand the **Volumes** section and click **Add Volume**.
|
||||
4. Choose **Add a new persistent volume (claim)**. This option will implicitly create the claim once you deploy the workload.
|
||||
5. Assign a **Name** for the claim, ie. `test-volume` and select the vSphere storage class created in the previous step.
|
||||
6. Enter the required **Capacity** for the volume. Then click **Define**.
|
||||
|
||||
|
||||
|
||||
7. Assign a path in the **Mount Point** field. This is the full path where the volume will be mounted in the container file system, e.g. `/persistent`.
|
||||
8. Click **Launch** to create the workload.
|
||||
|
||||
### Verifying Persistence of the Volume
|
||||
|
||||
1. From the context menu of the workload you just created, click **Execute Shell**.
|
||||
2. Note the directory at root where the volume has been mounted to (in this case `/persistent`).
|
||||
3. Create a file in the volume by executing the command `touch /<volumeMountPoint>/data.txt`.
|
||||
4. **Close** the shell window.
|
||||
5. Click on the name of the workload to reveal detail information.
|
||||
6. Open the context menu next to the Pod in the *Running* state.
|
||||
7. Delete the Pod by selecting **Delete**.
|
||||
8. Observe that the pod is deleted. Then a new pod is scheduled to replace it so that the workload maintains its configured scale of a single stateful pod.
|
||||
9. Once the replacement pod is running, click **Execute Shell**.
|
||||
10. Inspect the contents of the directory where the volume is mounted by entering `ls -l /<volumeMountPoint>`. Note that the file you created earlier is still present.
|
||||
|
||||
|
||||
|
||||
### Why to Use StatefulSets Instead of Deployments
|
||||
|
||||
You should always use [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for workloads consuming vSphere storage, as this resource type is designed to address a VMDK block storage caveat.
|
||||
|
||||
Since vSphere volumes are backed by VMDK block storage, they only support an [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) of `ReadWriteOnce`. This setting restricts the volume so that it can only be mounted to a single pod at a time, unless all pods consuming that volume are co-located on the same node. This behavior makes a deployment resource unusable for scaling beyond a single replica if it consumes vSphere volumes.
|
||||
|
||||
Even using a deployment resource with just a single replica may result in a deadlock situation while updating the deployment. If the updated pod is scheduled to a node different from where the existing pod lives, it will fail to start because the VMDK is still attached to the other node.
|
||||
|
||||
### Related Links
|
||||
|
||||
- [vSphere Storage for Kubernetes](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/)
|
||||
- [Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)
|
||||
+580
@@ -0,0 +1,580 @@
|
||||
---
|
||||
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 --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)](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#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 --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)](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#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 --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](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.md) 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.](../../../../pages-for-subheaders/checklist-for-production-ready-clusters.md)
|
||||
* 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.
|
||||
+232
@@ -0,0 +1,232 @@
|
||||
---
|
||||
title: Nodes and Node Pools
|
||||
weight: 2030
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's **Node** tab. Depending on the [option used](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) to provision the cluster, there are different node options available.
|
||||
|
||||
> If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters](../../../pages-for-subheaders/cluster-configuration.md#editing-clusters-with-yaml).
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Node options available for each cluster creation option](#node-options-available-for-each-cluster-creation-option)
|
||||
- [Nodes hosted by an infrastructure provider](#nodes-hosted-by-an-infrastructure-provider)
|
||||
- [Nodes provisioned by hosted Kubernetes providers](#nodes-provisioned-by-hosted-kubernetes-providers)
|
||||
- [Imported nodes](#imported-nodes)
|
||||
- [Managing and editing individual nodes](#managing-and-editing-individual-nodes)
|
||||
- [Viewing a node in the Rancher API](#viewing-a-node-in-the-rancher-api)
|
||||
- [Deleting a node](#deleting-a-node)
|
||||
- [Scaling nodes](#scaling-nodes)
|
||||
- [SSH into a node hosted by an infrastructure provider](#ssh-into-a-node-hosted-by-an-infrastructure-provider)
|
||||
- [Cordoning a node](#cordoning-a-node)
|
||||
- [Draining a node](#draining-a-node)
|
||||
- [Aggressive and safe draining options](#aggressive-and-safe-draining-options)
|
||||
- [Grace period](#grace-period)
|
||||
- [Timeout](#timeout)
|
||||
- [Drained and cordoned state](#drained-and-cordoned-state)
|
||||
- [Labeling a node to be ignored by Rancher](#labeling-a-node-to-be-ignored-by-rancher)
|
||||
|
||||
# Node Options Available for Each Cluster Creation Option
|
||||
|
||||
The following table lists which node options are available for each type of cluster in Rancher. Click the links in the **Option** column for more detailed information about each feature.
|
||||
|
||||
| Option | [Nodes Hosted by an Infrastructure Provider][1] | [Custom Node][2] | [Hosted Cluster][3] | [Imported Nodes][4] | Description |
|
||||
| ------------------------------------------------ | ------------------------------------------------ | ---------------- | ------------------- | ------------------- | ------------------------------------------------------------------ |
|
||||
| [Cordon](#cordoning-a-node) | ✓ | ✓ | ✓ | | Marks the node as unschedulable. |
|
||||
| [Drain](#draining-a-node) | ✓ | ✓ | ✓ | | Marks the node as unschedulable _and_ evicts all pods. |
|
||||
| [Edit](#managing-and-editing-individual-nodes) | ✓ | ✓ | ✓ | | Enter a custom name, description, label, or taints for a node. |
|
||||
| [View API](#viewing-a-node-in-the-rancher-api) | ✓ | ✓ | ✓ | | View API data. |
|
||||
| [Delete](#deleting-a-node) | ✓ | ✓ | | | Deletes defective nodes from the cluster. |
|
||||
| [Download Keys](#ssh-into-a-node-hosted-by-an-infrastructure-provider) | ✓ | | | | Download SSH key for in order to SSH into the node. |
|
||||
| [Node Scaling](#scaling-nodes) | ✓ | | | | Scale the number of nodes in the node pool up or down. |
|
||||
|
||||
[1]: cluster-provisioning/rke-clusters/node-pools/
|
||||
[2]: cluster-provisioning/rke-clusters/custom-nodes/
|
||||
[3]: cluster-provisioning/hosted-kubernetes-clusters/
|
||||
[4]: cluster-provisioning/imported-clusters/
|
||||
|
||||
### Nodes Hosted by an Infrastructure Provider
|
||||
|
||||
Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are [hosted in an infrastructure provider.](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md)
|
||||
|
||||
Clusters provisioned using [one of the node pool options](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#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.](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#about-node-auto-replace) This scale determines the number of active nodes that Rancher maintains for the cluster.
|
||||
|
||||
Rancher uses [node templates](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#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](../../../pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.md) are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly.
|
||||
|
||||
### Imported Nodes
|
||||
|
||||
Although you can deploy workloads to an [imported cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md) 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](../../../pages-for-subheaders/about-the-api.md).
|
||||
|
||||
# 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.](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#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](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#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](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md), you have the option of downloading its SSH key so that you can connect to it remotely from your desktop.
|
||||
|
||||
1. From the cluster hosted by an infrastructure provider, select **Nodes** from the main menu.
|
||||
|
||||
1. Find the node that you want to remote into. Select **⋮ > Download Keys**.
|
||||
|
||||
**Step Result:** A ZIP file containing files used for SSH is downloaded.
|
||||
|
||||
1. Extract the ZIP file to any location.
|
||||
|
||||
1. Open Terminal. Change your location to the extracted ZIP file.
|
||||
|
||||
1. Enter the following command:
|
||||
|
||||
```
|
||||
ssh -i id_rsa root@<IP_OF_HOST>
|
||||
```
|
||||
|
||||
# Cordoning a Node
|
||||
|
||||
_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.
|
||||
|
||||
# Draining a Node
|
||||
|
||||
_Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.
|
||||
|
||||
- For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.
|
||||
|
||||
- For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.
|
||||
|
||||
You can drain nodes that are in either a `cordoned` or `active` state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods.
|
||||
|
||||
However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value.
|
||||
|
||||
### Aggressive and Safe Draining Options
|
||||
|
||||
The node draining options are different based on your version of Rancher.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.2.x+">
|
||||
|
||||
There are two drain modes: aggressive and safe.
|
||||
|
||||
- **Aggressive Mode**
|
||||
|
||||
In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.
|
||||
|
||||
Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.
|
||||
|
||||
- **Safe Mode**
|
||||
|
||||
If a node has standalone pods or ephemeral data it will be cordoned but not drained.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.2.x">
|
||||
|
||||
The following list describes each drain option:
|
||||
|
||||
- **Even if there are pods not managed by a ReplicationController, ReplicaSet, Job, DaemonSet or StatefulSet**
|
||||
|
||||
These types of pods won't get rescheduled to a new node, since they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. Kubernetes forces you to choose this option (which will delete/evict these pods) or drain won't proceed.
|
||||
|
||||
- **Even if there are DaemonSet-managed pods**
|
||||
|
||||
Similar to above, if you have any daemonsets, drain would proceed only if this option is selected. Even when this option is on, pods won't be deleted since they'll immediately be replaced. On startup, Rancher currently has a few daemonsets running by default in the system, so this option is turned on by default.
|
||||
|
||||
- **Even if there are pods using emptyDir**
|
||||
|
||||
If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Similar to the first option, Kubernetes expects the implementation to decide what to do with these pods. Choosing this option will delete these pods.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Grace Period
|
||||
|
||||
The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.
|
||||
|
||||
### Timeout
|
||||
|
||||
The amount of time drain should continue to wait before giving up.
|
||||
|
||||
>**Kubernetes Known Issue:** The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was not enforced while draining a node 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
|
||||
|
||||
_Available as of 2.3.3_
|
||||
|
||||
Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.
|
||||
|
||||
Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.
|
||||
|
||||
In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.
|
||||
|
||||
You can label nodes to be ignored by using a setting in the Rancher UI, or by using `kubectl`.
|
||||
|
||||
> **Note:** There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state.
|
||||
|
||||
### Labeling Nodes to be Ignored with the Rancher UI
|
||||
|
||||
To add a node that is ignored by Rancher,
|
||||
|
||||
1. From the **Global** view, click the **Settings** tab.
|
||||
1. Go to the `ignore-node-name` setting and click **⋮ > Edit.**
|
||||
1. Enter a name that Rancher will use to ignore nodes. All nodes with this name will be ignored.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** Rancher will not wait to register nodes with this name. In the UI, the node will displayed with a grayed-out status. The node is still part of the cluster and can be listed with `kubectl`.
|
||||
|
||||
If the setting is changed afterward, the ignored nodes will continue to be hidden.
|
||||
|
||||
### Labeling Nodes to be Ignored with kubectl
|
||||
|
||||
To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label:
|
||||
|
||||
```
|
||||
cattle.rancher.io/node-status: ignore
|
||||
```
|
||||
|
||||
**Result:** If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with `kubectl`.
|
||||
|
||||
If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.
|
||||
|
||||
If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.
|
||||
|
||||
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings under `ignore-node-name`.
|
||||
+206
@@ -0,0 +1,206 @@
|
||||
---
|
||||
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
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/concepts/projects/
|
||||
- /rancher/v2.0-v2.4/en/tasks/projects/
|
||||
- /rancher/v2.0-v2.4/en/tasks/projects/create-project/
|
||||
- /rancher/v2.0-v2.4/en/tasks/projects/create-project/
|
||||
---
|
||||
|
||||
A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas.
|
||||
|
||||
A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.
|
||||
|
||||
This section describes how projects and namespaces work with Rancher. It covers the following topics:
|
||||
|
||||
- [About namespaces](#about-namespaces)
|
||||
- [About projects](#about-projects)
|
||||
- [The cluster's default project](#the-cluster-s-default-project)
|
||||
- [The system project](#the-system-project)
|
||||
- [Project authorization](#project-authorization)
|
||||
- [Pod security policies](#pod-security-policies)
|
||||
- [Creating projects](#creating-projects)
|
||||
- [Switching between clusters and projects](#switching-between-clusters-and-projects)
|
||||
|
||||
# About Namespaces
|
||||
|
||||
A namespace is a concept introduced by Kubernetes. According to the [official Kubernetes documentation on namespaces,](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
|
||||
|
||||
> Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all.
|
||||
|
||||
Namespaces provide the following functionality:
|
||||
|
||||
- **Providing a scope for names:** Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace.
|
||||
- **Resource quotas:** Namespaces provide a way to divide cluster resources between multiple users.
|
||||
|
||||
You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace.
|
||||
|
||||
You can assign the following resources directly to namespaces:
|
||||
|
||||
- [Workloads](../../../pages-for-subheaders/workloads-and-pods.md)
|
||||
- [Load Balancers/Ingress](../../../pages-for-subheaders/load-balancer-and-ingress-controller.md)
|
||||
- [Service Discovery Records](../../new-user-guides/kubernetes-resources-setup/create-services.md)
|
||||
- [Persistent Volume Claims](k8s-in-rancher/volumes-and-storage/persistent-volume-claims/)
|
||||
- [Certificates](../../new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md)
|
||||
- [ConfigMaps](../../new-user-guides/kubernetes-resources-setup/configmaps.md)
|
||||
- [Registries](../../new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md)
|
||||
- [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md)
|
||||
|
||||
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](../manage-projects/manage-namespaces.md).
|
||||
|
||||
### 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](../manage-projects/manage-namespaces.md) 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](k8s-in-rancher/projects-and-namespaces/project-members)).
|
||||
- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md).
|
||||
- Assign resources to the project.
|
||||
- Assign Pod Security Policies.
|
||||
|
||||
When you create a cluster, two projects are automatically created within it:
|
||||
|
||||
- [Default Project](#the-cluster-s-default-project)
|
||||
- [System Project](#the-system-project)
|
||||
|
||||
### The Cluster's Default Project
|
||||
|
||||
When you provision a cluster with Rancher, it automatically creates a `default` project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.
|
||||
|
||||
If you don't have a need for more than the default namespace, you also do not need more than the **Default** project in Rancher.
|
||||
|
||||
If you require another level of organization beyond the **Default** project, you can create more projects in Rancher to isolate namespaces, applications and resources.
|
||||
|
||||
### The System Project
|
||||
|
||||
_Available as of v2.0.7_
|
||||
|
||||
When troubleshooting, you can view the `system` project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers.
|
||||
|
||||
To open it, open the **Global** menu, and then select the `system` project for your cluster.
|
||||
|
||||
The `system` project:
|
||||
|
||||
- Is automatically created when you provision a cluster.
|
||||
- Lists all namespaces that exist in `v3/settings/system-namespaces`, if they exist.
|
||||
- Allows you to add more namespaces or move its namespaces to other projects.
|
||||
- Cannot be deleted because it's required for cluster operations.
|
||||
|
||||
>**Note:** In clusters where both:
|
||||
>
|
||||
> - The Canal network plug-in is in use.
|
||||
> - The Project Network Isolation option is enabled.
|
||||
>
|
||||
>The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health.
|
||||
|
||||
# Project Authorization
|
||||
|
||||
Standard users are only authorized for project access in two situations:
|
||||
|
||||
- An administrator, cluster owner or cluster member explicitly adds the standard user to the project's **Members** tab.
|
||||
- Standard users can access projects that they create themselves.
|
||||
|
||||
# Pod Security Policies
|
||||
|
||||
Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policluster-admin/pod-security-policy/) at the [project level](../manage-projects/manage-pod-security-policies.md) in addition to the [cluster level.](../pod-security-policy) However, as a best practice, we recommend applying Pod Security Policies at the cluster level.
|
||||
|
||||
# Creating Projects
|
||||
|
||||
This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.
|
||||
|
||||
1. [Name a new project.](#1-name-a-new-project)
|
||||
2. [Optional: Select a pod security policy.](#2-optional-select-a-pod-security-policy)
|
||||
3. [Recommended: Add project members.](#3-recommended-add-project-members)
|
||||
4. [Optional: Add resource quotas.](#4-optional-add-resource-quotas)
|
||||
|
||||
### 1. Name a New Project
|
||||
|
||||
1. From the **Global** view, choose **Clusters** from the main menu. From the **Clusters** page, open the cluster from which you want to create a project.
|
||||
|
||||
1. From the main menu, choose **Projects/Namespaces**. Then click **Add Project**.
|
||||
|
||||
1. Enter a **Project Name**.
|
||||
|
||||
### 2. Optional: Select a Pod Security Policy
|
||||
|
||||
This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md).
|
||||
|
||||
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](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#custom-project-roles).
|
||||
|
||||
To add members:
|
||||
|
||||
1. Click **Add Member**.
|
||||
1. From the **Name** combo box, search for a user or group that you want to assign project access. Note: You can only search for groups if external authentication is enabled.
|
||||
1. From the **Role** drop-down, choose a role. For more information, refer to the [documentation on project roles.](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
|
||||
|
||||
### 4. Optional: Add Resource Quotas
|
||||
|
||||
_Available as of v2.1.0_
|
||||
|
||||
Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas](k8s-in-rancher/projects-and-namespaces/resource-quotas).
|
||||
|
||||
To add a resource quota,
|
||||
|
||||
1. Click **Add Quota**.
|
||||
1. Select a Resource Type. For more information, see [Resource Quotas.](k8s-in-rancher/projects-and-namespaces/resource-quotas/).
|
||||
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](../../../pages-for-subheaders/manage-project-resource-quotas.md) Note: This option is available as of v2.2.0.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view.
|
||||
|
||||
| Field | Description |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| Project Limit | The overall resource limit for the project. |
|
||||
| Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit. |
|
||||
|
||||
# Switching between Clusters and Projects
|
||||
|
||||
To switch between clusters and projects, use the **Global** drop-down available in the main menu.
|
||||
|
||||
|
||||
|
||||
Alternatively, you can switch between projects and clusters using the main menu.
|
||||
|
||||
- To switch between clusters, open the **Global** view and select **Clusters** from the main menu. Then open a cluster.
|
||||
- To switch between projects, open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open.
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Restoring a Cluster from Backup
|
||||
weight: 2050
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
etcd backup and recovery for [Rancher launched Kubernetes clusters](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md) 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](backing-up-etcd.md#configuring-recurring-snapshots), but [one-time snapshots](backing-up-etcd.md#one-time-snapshots) can easily be taken as well. Rancher allows restore from [saved snapshots](#restoring-a-cluster-from-a-snapshot) or if you don't have any snapshots, you can still [restore etcd](#recovering-etcd-without-a-snapshot).
|
||||
|
||||
As of Rancher v2.4.0, clusters can also be restored to a prior Kubernetes version and cluster configuration.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Viewing Available Snapshots](#viewing-available-snapshots)
|
||||
- [Restoring a Cluster from a Snapshot](#restoring-a-cluster-from-a-snapshot)
|
||||
- [Recovering etcd without a Snapshot](#recovering-etcd-without-a-snapshot)
|
||||
- [Enabling snapshot features for clusters created before Rancher v2.2.0](#enabling-snapshot-features-for-clusters-created-before-rancher-v2-2-0)
|
||||
|
||||
## Viewing Available Snapshots
|
||||
|
||||
The list of all available snapshots for the cluster is available.
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to view snapshots.
|
||||
|
||||
2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.
|
||||
|
||||
## Restoring a Cluster from a Snapshot
|
||||
|
||||
If your Kubernetes cluster is broken, you can restore the cluster from a snapshot.
|
||||
|
||||
Restores changed in Rancher v2.4.0.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.4.0+">
|
||||
|
||||
Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the `cluster.yml.` These components allow you to select from the following options when restoring a cluster from a snapshot:
|
||||
|
||||
- **Restore just the etcd contents:** This 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](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md#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.](backing-up-etcd.md#configuring-recurring-snapshots)
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to restore from a snapshots.
|
||||
|
||||
2. Click the **⋮ > Restore Snapshot**.
|
||||
|
||||
3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.
|
||||
|
||||
4. In the **Restoration Type** field, choose one of the restore options described above.
|
||||
|
||||
5. Click **Save**.
|
||||
|
||||
**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.4.0">
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - Make sure your etcd nodes are healthy. If you are restoring a cluster with unavailable etcd nodes, it's recommended that all etcd nodes are removed from Rancher before attempting to restore. For clusters in which Rancher used node pools to provision [nodes in an infrastructure provider](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md), new etcd nodes will automatically be created. For [custom clusters](../../../pages-for-subheaders/use-existing-nodes.md), please ensure that you add new etcd nodes to the cluster.
|
||||
> - To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.](backing-up-etcd.md#configuring-recurring-snapshots)
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to restore from a snapshot.
|
||||
|
||||
2. Click the **⋮ > Restore Snapshot**.
|
||||
|
||||
3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.
|
||||
|
||||
4. Click **Save**.
|
||||
|
||||
**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Recovering etcd without a Snapshot
|
||||
|
||||
If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. 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](../../../pages-for-subheaders/use-existing-nodes.md) and you want to reuse an old node, you are required to [clean up the nodes](faq/cleaning-cluster-nodes/) before attempting to add them back into a cluster.
|
||||
|
||||
# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0
|
||||
|
||||
If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) 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](restoring-etcd.md).
|
||||
+87
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Certificate Rotation
|
||||
weight: 2040
|
||||
---
|
||||
|
||||
> **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:
|
||||
|
||||
- etcd
|
||||
- kubelet
|
||||
- kube-apiserver
|
||||
- kube-proxy
|
||||
- kube-scheduler
|
||||
- kube-controller-manager
|
||||
|
||||
|
||||
### Certificate Rotation in Rancher v2.2.x
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI.
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to rotate certificates.
|
||||
|
||||
2. Select the **⋮ > Rotate Certificates**.
|
||||
|
||||
3. 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
|
||||
|
||||
4. Click **Save**.
|
||||
|
||||
**Results:** The selected certificates will be rotated and the related services will be restarted to start using the new certificate.
|
||||
|
||||
> **Note:** 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.
|
||||
|
||||
|
||||
### Certificate Rotation in Rancher v2.1.x and v2.0.x
|
||||
|
||||
_Available as of v2.0.14 and v2.1.9_
|
||||
|
||||
Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the API.
|
||||
|
||||
1. In the **Global** view, navigate to the cluster that you want to rotate certificates.
|
||||
|
||||
2. Select the **⋮ > View in API**.
|
||||
|
||||
3. Click on **RotateCertificates**.
|
||||
|
||||
4. Click on **Show Request**.
|
||||
|
||||
5. Click on **Send Request**.
|
||||
|
||||
**Results:** All Kubernetes certificates will be rotated.
|
||||
|
||||
### Rotating Expired Certificates After Upgrading Older Rancher Versions
|
||||
|
||||
If you are upgrading from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your clusters have expired certificates, some manual steps are required to complete the certificate rotation.
|
||||
|
||||
1. For the `controlplane` and `etcd` nodes, log in to each corresponding host and check if the certificate `kube-apiserver-requestheader-ca.pem` is in the following directory:
|
||||
|
||||
```
|
||||
cd /etc/kubernetes/.tmp
|
||||
```
|
||||
|
||||
If the certificate is not in the directory, perform the following commands:
|
||||
|
||||
```
|
||||
cp kube-ca.pem kube-apiserver-requestheader-ca.pem
|
||||
cp kube-ca-key.pem kube-apiserver-requestheader-ca-key.pem
|
||||
cp kube-apiserver.pem kube-apiserver-proxy-client.pem
|
||||
cp kube-apiserver-key.pem kube-apiserver-proxy-client-key.pem
|
||||
```
|
||||
|
||||
If the `.tmp` directory does not exist, you can copy the entire SSL certificate to `.tmp`:
|
||||
|
||||
```
|
||||
cp -r /etc/kubernetes/ssl /etc/kubernetes/.tmp
|
||||
```
|
||||
|
||||
1. Rotate the certificates. For Rancher v2.0.x and v2.1.x, use the [Rancher API.](#certificate-rotation-in-rancher-v2-1-x-and-v2-0-x) For Rancher 2.2.x, [use the UI.](#certificate-rotation-in-rancher-v2-2-x)
|
||||
|
||||
1. After the command is finished, check if the `worker` nodes are Active. If not, log in to each `worker` node and restart the kubelet and proxy.
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Adding Users to Projects
|
||||
weight: 2505
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/projects/add-project-members/
|
||||
- /rancher/v2.0-v2.4/en/k8s-in-rancher/projects-and-namespaces/project-members/
|
||||
---
|
||||
|
||||
If you want to provide a user with access and permissions to _specific_ projects and resources within a cluster, assign the user a project membership.
|
||||
|
||||
You can add members to a project as it is created, or add them to an existing project.
|
||||
|
||||
>**Tip:** Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members](cluster-provisioning/cluster-members/) instead.
|
||||
|
||||
### Adding Members to a New Project
|
||||
|
||||
You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the [cluster administration section.](k8s-in-rancher/projects-and-namespaces/)
|
||||
|
||||
### Adding Members to an Existing Project
|
||||
|
||||
Following project creation, you can add users as project members so that they can access its resources.
|
||||
|
||||
1. From the **Global** view, open the project that you want to add members to.
|
||||
|
||||
2. From the main menu, select **Members**. Then click **Add Member**.
|
||||
|
||||
3. Search for the user or group that you want to add to the project.
|
||||
|
||||
If external authentication is configured:
|
||||
|
||||
- Rancher returns users from your external authentication source as you type.
|
||||
|
||||
- A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in.
|
||||
|
||||
>**Note:** If you are logged in as a local user, external users do not display in your search results.
|
||||
|
||||
1. Assign the user or group **Project** roles.
|
||||
|
||||
[What are Project Roles?](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
>- Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned.
|
||||
>
|
||||
>- 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.
|
||||
>
|
||||
>- For `Custom` roles, you can modify the list of individual roles available for assignment.
|
||||
>
|
||||
> - To add roles to the list, [Add a Custom Role](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md).
|
||||
> - To remove roles from the list, [Lock/Unlock Roles](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md).
|
||||
|
||||
**Result:** The chosen users are added to the project.
|
||||
|
||||
- To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user.
|
||||
- To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles.
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Rancher's CI/CD Pipelines
|
||||
description: Use Rancher’s CI/CD pipeline to automatically checkout code, run builds or scripts, publish Docker images, and deploy software to users
|
||||
weight: 4000
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/concepts/ci-cd-pipelines/
|
||||
- /rancher/v2.0-v2.4/en/tasks/pipelines/
|
||||
- /rancher/v2.0-v2.4/en/tools/pipelines/configurations/
|
||||
---
|
||||
Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.
|
||||
|
||||
After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:
|
||||
|
||||
- Build your application from code to image.
|
||||
- Validate your builds.
|
||||
- Deploy your build images to your cluster.
|
||||
- Run unit tests.
|
||||
- Run regression tests.
|
||||
|
||||
For details, refer to the [pipelines](k8s-in-rancher/pipelines) section.
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Namespaces
|
||||
weight: 2520
|
||||
---
|
||||
|
||||
Within Rancher, you can further divide projects into different [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the `default` namespace, you can use multiple namespaces to isolate applications and resources.
|
||||
|
||||
Although you assign resources at the project level so that each namespace in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace.
|
||||
|
||||
Resources that you can assign directly to namespaces include:
|
||||
|
||||
- [Workloads](../../../pages-for-subheaders/workloads-and-pods.md)
|
||||
- [Load Balancers/Ingress](../../../pages-for-subheaders/load-balancer-and-ingress-controller.md)
|
||||
- [Service Discovery Records](../../new-user-guides/kubernetes-resources-setup/create-services.md)
|
||||
- [Persistent Volume Claims](k8s-in-rancher/volumes-and-storage/persistent-volume-claims/)
|
||||
- [Certificates](../../new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md)
|
||||
- [ConfigMaps](../../new-user-guides/kubernetes-resources-setup/configmaps.md)
|
||||
- [Registries](../../new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md)
|
||||
- [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md)
|
||||
|
||||
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.
|
||||
|
||||
> **Note:** If you create a namespace with `kubectl`, it may be unusable because `kubectl` doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to [create a namespace through Rancher](manage-namespaces.md) to ensure that you will have permission to access the namespace.
|
||||
|
||||
|
||||
### Creating Namespaces
|
||||
|
||||
Create a new namespace to isolate apps and resources in a project.
|
||||
|
||||
>**Tip:** When working with project resources that you can assign to a namespace (i.e., [workloads](../../new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md), [certificates](../../new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md), [ConfigMaps](../../new-user-guides/kubernetes-resources-setup/configmaps.md), etc.) you can create a namespace on the fly.
|
||||
|
||||
1. From the **Global** view, open the project where you want to create a namespace.
|
||||
|
||||
>**Tip:** As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can create them from the cluster level as well.
|
||||
|
||||
1. From the main menu, select **Namespace**. The click **Add Namespace**.
|
||||
|
||||
1. **Optional:** If your project has [Resource Quotas](k8s-in-rancher/projects-and-namespaces/resource-quotas) in effect, you can override the default resource **Limits** (which places a cap on the resources that the namespace can consume).
|
||||
|
||||
1. Enter a **Name** and then click **Create**.
|
||||
|
||||
**Result:** Your namespace is added to the project. You can begin assigning cluster resources to the namespace.
|
||||
|
||||
### Moving Namespaces to Another Project
|
||||
|
||||
Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application.
|
||||
|
||||
1. From the **Global** view, open the cluster that contains the namespace you want to move.
|
||||
|
||||
1. From the main menu, select **Projects/Namespaces**.
|
||||
|
||||
1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one.
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
>- Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking.
|
||||
>- You cannot move a namespace into a project that already has a [resource quota](k8s-in-rancher/projects-and-namespaces/resource-quotas/) configured.
|
||||
>- If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace.
|
||||
|
||||
1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**.
|
||||
|
||||
**Result:** Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project.
|
||||
|
||||
### Editing Namespace Resource Quotas
|
||||
|
||||
You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources.
|
||||
|
||||
For more information, see how to [edit namespace resource quotas](project-admin//resource-quotas/override-namespace-default/).
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Pod Security Policies
|
||||
weight: 5600
|
||||
---
|
||||
|
||||
> These cluster options are only available for [clusters in which Rancher has launched Kubernetes](../../../pages-for-subheaders/launch-kubernetes-with-rancher.md).
|
||||
|
||||
You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md).
|
||||
- Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [the documentation about adding a pod security policy to a cluster](../manage-clusters/add-a-pod-security-policy.md).
|
||||
|
||||
### Applying a Pod Security Policy
|
||||
|
||||
1. From the **Global** view, find the cluster containing the project you want to apply a PSP to.
|
||||
1. From the main menu, select **Projects/Namespaces**.
|
||||
1. Find the project that you want to add a PSP to. From that project, select **⋮ > Edit**.
|
||||
1. From the **Pod Security Policy** drop-down, select the PSP you want to apply to the project.
|
||||
Assigning a PSP to a project will:
|
||||
|
||||
- Override the cluster's default PSP.
|
||||
- Apply the PSP to the project.
|
||||
- Apply the PSP to any namespaces you add to the project later.
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The PSP is applied to the project and any namespaces added to the project.
|
||||
|
||||
>**Note:** Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: How Resource Quotas Work in Rancher Projects
|
||||
weight: 1
|
||||
---
|
||||
|
||||
Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). However, in Rancher, resource quotas have been extended so that you can apply them to projects.
|
||||
|
||||
In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times.
|
||||
|
||||
In the following diagram, a Kubernetes administrator is trying to enforce a resource quota without Rancher. The administrator wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (`Namespace 1-4`) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The administrator has to create four different resource quotas that have the same specs configured (`Resource Quota 1-4`) and apply them individually.
|
||||
|
||||
<sup>Base Kubernetes: Unique Resource Quotas Being Applied to Each Namespace</sup>
|
||||
|
||||
|
||||
Resource quotas are a little different in Rancher. In Rancher, you apply a resource quota to the project, and then the quota propagates to each namespace, whereafter Kubernetes enforces your limits using the native version of resource quotas. If you want to change the quota for a specific namespace, you can override it.
|
||||
|
||||
The resource quota includes two limits, which you set while creating or editing a project:
|
||||
<a id="project-limits"></a>
|
||||
|
||||
- **Project Limits:**
|
||||
|
||||
This set of values configures an overall resource limit for the project. If you try to add a new namespace to the project, Rancher uses the limits you've set to validate that the project has enough resources to accommodate the namespace. In other words, if you try to move a namespace into a project near its resource quota, Rancher blocks you from moving the namespace.
|
||||
|
||||
- **Namespace Default Limits:**
|
||||
|
||||
This value is the default resource limit available for each namespace. When the resource quota is created at the project level, this limit is automatically propagated to each namespace in the project. Each namespace is bound to this default limit unless you override it.
|
||||
|
||||
In the following diagram, a Rancher administrator wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (`Namespace 1-4`). However, in Rancher, the administrator can set a resource quota for the project (`Project Resource Quota`) rather than individual namespaces. This quota includes resource limits for both the entire project (`Project Limit`) and individual namespaces (`Namespace Default Limit`). Rancher then propagates the `Namespace Default Limit` quotas to each namespace (`Namespace Resource Quota`) when created.
|
||||
|
||||
<sup>Rancher: Resource Quotas Propagating to Each Namespace</sup>
|
||||
|
||||
|
||||
Let's highlight some more nuanced functionality. If a quota is deleted at the project level, it will also be removed from all namespaces contained within that project, despite any overrides that may exist. Further, updating an existing namespace default limit for a quota at the project level will not result in that value being propagated to existing namespaces in the project; the updated value will only be applied to newly created namespaces in that project. To update a namespace default limit for existing namespaces you can delete and subsequently recreate the quota at the project level with the new default value. This will result in the new default value being applied to all existing namespaces in the project.
|
||||
|
||||
The following table explains the key differences between the two quota types.
|
||||
|
||||
| Rancher Resource Quotas | Kubernetes Resource Quotas |
|
||||
| ---------------------------------------------------------- | -------------------------------------------------------- |
|
||||
| Applies to projects and namespace. | Applies to namespaces only. |
|
||||
| Creates resource pool for all namespaces in project. | Applies static resource limits to individual namespaces. |
|
||||
| Applies resource quotas to namespaces through propagation. | Applies only to the assigned namespace.
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Overriding the Default Limit for a Namespace
|
||||
weight: 2
|
||||
---
|
||||
|
||||
Although the **Namespace Default Limit** propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace.
|
||||
|
||||
In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the namespace limits](k8s-in-rancher/projects-and-namespaces/) for `Namespace 3` so that the namespace can access more resources.
|
||||
|
||||
<sup>Namespace Default Limit Override</sup>
|
||||
|
||||
|
||||
How to: [Editing Namespace Resource Quotas](k8s-in-rancher/projects-and-namespaces/)
|
||||
|
||||
### Editing Namespace Resource Quotas
|
||||
|
||||
If there is a [resource quota](k8s-in-rancher/projects-and-namespaces/resource-quotas) configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources.
|
||||
|
||||
1. From the **Global** view, open the cluster that contains the namespace for which you want to edit the resource quota.
|
||||
|
||||
1. From the main menu, select **Projects/Namespaces**.
|
||||
|
||||
1. Find the namespace for which you want to edit the resource quota. Select **⋮ > Edit**.
|
||||
|
||||
1. Edit the Resource Quota **Limits**. These limits determine the resources available to the namespace. The limits must be set within the configured project limits.
|
||||
|
||||
For more information about each **Resource Type**, see [Resource Quotas](k8s-in-rancher/projects-and-namespaces/resource-quotas/).
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>- If a resource quota is not configured for the project, these options will not be available.
|
||||
>- If you enter limits that exceed the configured project limits, Rancher will not let you save your edits.
|
||||
|
||||
**Result:** Your override is applied to the namespace's resource quota.
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Resource Quota Type Reference
|
||||
weight: 4
|
||||
---
|
||||
|
||||
When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types.
|
||||
|
||||
| Resource Type | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.<sup>1</sup> |
|
||||
| CPU Reservation* | The minimum amount of CPU (in millicores) guaranteed to the project/namespace.<sup>1</sup> |
|
||||
| Memory Limit* | The maximum amount of memory (in bytes) allocated to the project/namespace.<sup>1</sup> |
|
||||
| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.<sup>1</sup> |
|
||||
| Storage Reservation | The minimum amount of storage (in gigabytes) guaranteed to the project/namespace. |
|
||||
| Services Load Balancers | The maximum number of load balancers services that can exist in the project/namespace. |
|
||||
| Services Node Ports | The maximum number of node port services that can exist in the project/namespace. |
|
||||
| Pods | The maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of `.status.phase in (Failed, Succeeded)` equal to true). |
|
||||
| Services | The maximum number of services that can exist in the project/namespace. |
|
||||
| ConfigMaps | The maximum number of ConfigMaps that can exist in the project/namespace. |
|
||||
| Persistent Volume Claims | The maximum number of persistent volume claims that can exist in the project/namespace. |
|
||||
| Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. |
|
||||
| Secrets | The maximum number of secrets that can exist in the project/namespace. |
|
||||
|
||||
>**<sup>*</sup>** When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. As of v2.2.0, a container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Setting Container Default Resource Limits
|
||||
weight: 3
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required.
|
||||
|
||||
To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.
|
||||
|
||||
### Editing the Container Default Resource Limit
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Edit [container default resource limit](k8s-in-rancher/projects-and-namespaces/resource-quotas/) when:
|
||||
|
||||
- You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container.
|
||||
- You want to edit the default container resource limit.
|
||||
|
||||
1. From the **Global** view, open the cluster containing the project to which you want to edit the container default resource limit.
|
||||
1. From the main menu, select **Projects/Namespaces**.
|
||||
1. Find the project that you want to edit the container default resource limit. From that project, select **⋮ > Edit**.
|
||||
1. Expand **Container Default Resource Limit** and edit the values.
|
||||
|
||||
### Resource Limit Propagation
|
||||
|
||||
When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers.
|
||||
|
||||
> **Note:** Before v2.2.0, you could not launch catalog applications that did not have any limits set. With v2.2.0, you can set a default container resource limit on a project and launch any catalog applications.
|
||||
|
||||
Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation.
|
||||
|
||||
### Container Resource Quota Types
|
||||
|
||||
The following resource limits can be configured:
|
||||
|
||||
| Resource Type | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CPU Limit | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the container.|
|
||||
| CPU Reservation | The minimum amount of CPU (in millicores) guaranteed to the container. |
|
||||
| Memory Limit | The maximum amount of memory (in bytes) allocated to the container. |
|
||||
| Memory Reservation | The minimum amount of memory (in bytes) guaranteed to the container.
|
||||
Reference in New Issue
Block a user