diff --git a/Dockerfile.dev b/Dockerfile.dev index 26ce67c09b6..2f2bab6856c 100644 --- a/Dockerfile.dev +++ b/Dockerfile.dev @@ -1,4 +1,5 @@ FROM rancher/docs:build +ENV HUGO_ENV dev VOLUME ["/site"] WORKDIR /run @@ -6,7 +7,6 @@ COPY package.json /run/ RUN ln -s /site/config.toml /run \ && ln -s /site/.eslintrc.js /run \ - && ln -s /site/netlify.toml /run \ && ln -s /site/archetypes /run \ && ln -s /site/content /run \ && ln -s /site/data /run \ diff --git a/Dockerfile.prod b/Dockerfile.prod index 65bc10b5b7a..a0ff19643a4 100644 --- a/Dockerfile.prod +++ b/Dockerfile.prod @@ -1,10 +1,10 @@ FROM rancher/docs:build as build +ENV HUGO_ENV production WORKDIR /run COPY gulpfile.babel.js /run/ COPY .eslintrc.js /run/ COPY config.toml /run/ -COPY netlify.toml /run/ COPY archetypes archetypes COPY data data COPY layouts layouts @@ -12,8 +12,6 @@ COPY scripts scripts COPY content content COPY src src -ENV HUGO_ENV production - ADD https://github.com/rancherlabs/website-theme/archive/master.tar.gz master.tar.gz RUN tar -xzf master.tar.gz --strip 1 -C /run/node_modules/rancher-website-theme && rm master.tar.gz diff --git a/Dockerfile.staging b/Dockerfile.staging index fc2fbeee1df..1bfdf364ae1 100644 --- a/Dockerfile.staging +++ b/Dockerfile.staging @@ -1,10 +1,10 @@ FROM rancher/docs:build as build +ENV HUGO_ENV staging WORKDIR /run COPY gulpfile.babel.js /run/ COPY .eslintrc.js /run/ COPY config.toml /run/ -COPY netlify.toml /run/ COPY archetypes archetypes COPY data data COPY layouts layouts @@ -12,8 +12,6 @@ COPY scripts scripts COPY content content COPY src src -ENV HUGO_ENV production - ADD https://github.com/rancherlabs/website-theme/archive/master.tar.gz master.tar.gz RUN tar -xzf master.tar.gz --strip 1 -C /run/node_modules/rancher-website-theme && rm master.tar.gz diff --git a/config.toml b/config.toml index 7f02944b155..f53ad6a92f6 100644 --- a/config.toml +++ b/config.toml @@ -6,9 +6,11 @@ themesDir = "node_modules" pluralizeListTitles = false enableRobotsTXT = true -pygmentsCodeFences=true -pygmentsCodeFencesGuessSyntax=true +pygmentsCodeFences = true +pygmentsCodeFencesGuessSyntax = true +[blackfriday] +hrefTargetBlank = true [permalinks] inside-pages = "/:filename/" diff --git a/content/rancher/v2.x/en/admin-settings/authentication/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/_index.md index 3471e124701..c1bb5986ac5 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/_index.md @@ -1,9 +1,9 @@ --- title: Authentication -weight: 50 +weight: 1110 aliases: - -/rancher/v2.x/en/concepts/global-configuration/authentication/ - -/rancher/v2.x/en/tasks/global-configuration/authentication/ + - /rancher/v2.x/en/concepts/global-configuration/authentication/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/ --- One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters. @@ -26,8 +26,6 @@ However, Rancher also provides local authentication. In most cases, you should use an external authentication service over local, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if Active Directory is down. -For more information on how to configure external authentication or local authentication, see [Authentication](../../../tasks/global-configuration/authentication/). - ### External Authentication Configuration and Principal Users Configuration of external authentication requires: @@ -53,9 +51,8 @@ Configuration of external authentication affects how principal users are managed ![Sign In External Principal]({{< baseurl >}}/img/rancher/sign-in-external.png) -5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page. +5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page. ![Sign In External Principal]({{< baseurl >}}/img/rancher/users-page.png) 6. The external principal and the local principal share the same access rights. - diff --git a/content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md new file mode 100644 index 00000000000..42307197d74 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md @@ -0,0 +1,191 @@ +--- +title: Configuring Active Directory (AD) +weight: 1112 +aliases: + - /rancher/v2.x/en/tasks/global-configuration/authentication/active-directory/ +--- + +Rancher can be configured to communicate with an existing Microsoft Active Directory server for the purpose user authentication. This allows users to use their AD account credentials for login into the Rancher UI as well as managing access to clusters and projects based on AD user identity or group membership. + +> **Note:** +> +> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + +## Prerequisites + +You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform 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 privileges to view, but not modify other 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 both **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 that will be used by Rancher to lookup users and groups (see [Prerequisites](#prerequisites)). You must specify this username in the logon (slashed) format, e.g. "mydomain\rancheruser". | +| Service Account Password | The password for the service account. | +| Default Login Domain | Enter your AD domain, e.g. "acme". | +| 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. | +| Username Attribute | The user attribute whose value is suitable as a display name. | +| Login Attribute | The attribute whose value matches the username part of your users AD credentials, ie. what they would enter when logging in to Rancher. | +| 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, Rancher queries the AD server and attempts to match fields by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. As of Rancher v2.0.1, this parameter defaults to: "sAMAccountName\|sn\|givenName".| +| 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. | +| 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`. | +| Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). | + +--- + +### Test Authentication + +When you have completed the configuration, proceed by testing the connection to the AD server with your own AD credentials. + +> **Note:** +> +> On completing this step of the configuration, the AD user pertaining to the credentials entered here will be mapped to the local principal account. You should therefore ensure to specifically enter credentials of an AD account that you want to be assigned the administrative role in Rancher going forward. + +1. Enter the **username** and **password** for your AD account. +2. Click **Authenticate with Active Directory** to test the Active Directory connection and map this user to the local admin account. + +**Result:** + +- AD authentication is configured. +- You are signed into Rancher with your AD account (mapped to the local user assigned the administrator role, ie. the local principal account). + +> **Note:** +> +> You will still be able to login using the locally configured `admin` account and password in case of a disruption of AD 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 hirarchy 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 the user account (`sAMAccountNam=jdoe`), returning the attributes for said user: + +![LDAP User]({{< baseurl >}}/img/rancher/ldapsearch-user.png) + +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] + +With regards to the `Search Attribute` parameter, it makes sense here to set it to **sAMAccountName|name**. This will allow users to be added in the Rancher UI both 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: + +![LDAP Group]({{< baseurl >}}/img/rancher/ldapsearch-group.png) + +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 issue cause. Please refer to [How can I enable debug logging]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation. \ No newline at end of file diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-azure-ad/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/azure-ad/_index.md similarity index 96% rename from content/rancher/v2.x/en/admin-settings/authentication/configuring-azure-ad/_index.md rename to content/rancher/v2.x/en/admin-settings/authentication/azure-ad/_index.md index c2bac9fabe5..5fefc106cac 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-azure-ad/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/azure-ad/_index.md @@ -1,8 +1,8 @@ --- title: Configuring Azure AD -weight: 75 +weight: 1115 aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/azure-ad/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/azure-ad/ --- _Available as of v2.0.3_ @@ -11,7 +11,7 @@ If you have an instance of Active Directory (AD) hosted in Azure, you can config >**Prerequisite:** Have an instance of Azure AD configured. ->**Note:** Most of this procedure, with the exception of [Configure Azure AD in Rancher](#configure-azure-ad-in-rancher), takes place from the [Microsoft Azure Portal](https://portal.azure.com/). +>**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). ## Azure Active Directory Configuration Outline diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-ad/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/configuring-ad/_index.md deleted file mode 100644 index 024b18ff2a1..00000000000 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-ad/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Configuring Active Directory (AD) -weight: 50 -aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/active-directory/ ---- - -In environments using Microsoft AD, you can configure Rancher to allow sign on using AD credentials. - ->**Prerequisites:** -> ->- Have an AD server configured. ->- Create a service account in AD with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key. ->- Read [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). - -1. Sign into Rancher using a local user assigned `administrator` global permissions (i.e., the _local principal_). - -2. From the **Global** view, select **Security > Authentication** from the main menu. - -3. Select **AD**. - -4. Complete the **Configure an AD 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. -
-
- >**User Search Base vs. Group Search Base** - > - >Search base allows Rancher to search for users and groups that are in your AD. 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 AD deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step. - - >**Search Attribute** As of Rancher v2.0.1, the Search Attribute field defaults with three specific values: `sAMAccountName|sn|givenName`. After AD is configured, when a user enters text to add users or groups, Rancher automatically queries the AD server and attempts to match fields by sAMAccountName, 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 `sAMAccountName|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields. - > - > * `sAMAccountName`: Username - > * `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 AD username and password in **Authenticate with AD** to confirm that Rancher is configured to use AD authentication. - -**Result:** - -- AD authentication is configured. -- You are signed into Rancher with your AD account (i.e., the _external principal_). diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-freeipa/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/freeipa/_index.md similarity index 97% rename from content/rancher/v2.x/en/admin-settings/authentication/configuring-freeipa/_index.md rename to content/rancher/v2.x/en/admin-settings/authentication/freeipa/_index.md index 6fb0afa428a..7158f26a6a8 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-freeipa/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/freeipa/_index.md @@ -1,8 +1,8 @@ --- title: Configuring FreeIPA -weight: 150 +weight: 1114 aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/freeipa/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/freeipa/ --- _Available as of v2.0.5_ diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-github/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/github/_index.md similarity index 96% rename from content/rancher/v2.x/en/admin-settings/authentication/configuring-github/_index.md rename to content/rancher/v2.x/en/admin-settings/authentication/github/_index.md index 271f45e3627..55e505e26f3 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-github/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/github/_index.md @@ -1,8 +1,8 @@ --- title: Configuring GitHub -weight: 100 +weight: 1116 aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/github/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/github/ --- In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials. diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-local-authentication/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/local/_index.md similarity index 75% rename from content/rancher/v2.x/en/admin-settings/authentication/configuring-local-authentication/_index.md rename to content/rancher/v2.x/en/admin-settings/authentication/local/_index.md index e65390436cf..687d9ab200b 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-local-authentication/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/local/_index.md @@ -1,12 +1,12 @@ --- title: Configuring Local Authentication -weight: 25 +weight: 1111 aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/local-authentication/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/local-authentication/ --- Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if you your external authentication service encounters issues. 1. From the **Global** view, select **Users** from the main menu. -2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done. \ No newline at end of file +2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done. diff --git a/content/rancher/v2.x/en/admin-settings/authentication/configuring-openldap/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md similarity index 97% rename from content/rancher/v2.x/en/admin-settings/authentication/configuring-openldap/_index.md rename to content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md index b442a5f1a82..c577e9a2131 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/configuring-openldap/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md @@ -1,8 +1,8 @@ --- title: Configuring OpenLDAP -weight: 125 +weight: 1113 aliases: - -/rancher/v2.x/en/tasks/global-configuration/authentication/openLDAP/ + - /rancher/v2.x/en/tasks/global-configuration/authentication/openldap/ --- _Available as of v2.0.5_ diff --git a/content/rancher/v2.x/en/admin-settings/pod-security-policies/_index.md b/content/rancher/v2.x/en/admin-settings/pod-security-policies/_index.md index 9857571848c..909a232e594 100644 --- a/content/rancher/v2.x/en/admin-settings/pod-security-policies/_index.md +++ b/content/rancher/v2.x/en/admin-settings/pod-security-policies/_index.md @@ -1,9 +1,10 @@ --- title: Pod Security Policies -weight: 100 +weight: 1135 aliases: - -/rancher/v2.x/en/concepts/global-configuration/pod-security-policies - -/rancher/v2.x/en/tasks/global-configuration/pod-security-policies + - /rancher/v2.x/en/concepts/global-configuration/pod-security-policies/ + - /rancher/v2.x/en/tasks/global-configuration/pod-security-policies/ + - /rancher/v2.x/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 is forbidden: unable to validate...`. @@ -51,7 +52,15 @@ Using Rancher, you can create a Pod Security Policy using our GUI rather than cr ### What's Next? -Now that you've created a Pod Security Policy, you can apply it to clusters and projects. For more information, see [Adding a Pod Security Policy to a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-a-pod-security-policy). +You can add a Pod Security Policy (PSPs hereafter) in the following contexts: + +- [When creating a cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/) +- [When editing an existing cluster]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/) +- [When creating a project]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/#creating-a-project/) +- [When editing an existing project]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/editing-projects/) + +> **Note:** We recommend adding PSPs during cluster and project creation instead of adding it to an existing one. + diff --git a/content/rancher/v2.x/en/admin-settings/rbac/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/_index.md index e92a88dacfd..24bfa38de12 100644 --- a/content/rancher/v2.x/en/admin-settings/rbac/_index.md +++ b/content/rancher/v2.x/en/admin-settings/rbac/_index.md @@ -1,11 +1,11 @@ --- -title: RBAC -weight: 75 +title: Roles in Rancher +weight: 1125 aliases: - -/rancher/v2.x/en/admin-settings/rbac/ + - /rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/ --- -Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/authentication), users can either be local or external. +Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/), users can either be local or external. After you configure external authentication, the users that display on the **Users** page changes. @@ -17,183 +17,12 @@ After you configure external authentication, the users that display on the **Use Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by _global permissions_, and _cluster and project roles_. -- **Global Permissions:** +- **[Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/):** Define user authorization outside the scope of any particular cluster. -- **Cluster and Project Roles:** +- **[Cluster and Project Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/):** Define user authorization inside the specific cluster or project where they are assigned the role. Both global permissions and cluster and project roles are implemented on top of [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). Therefore, enforcement of permissions and roles is performed by Kubernetes. - -### Global Permissions - -Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are two default global permissions: `Administrator` and `Standard User`. - -- **Administrator:** - - These users have full control over the entire Rancher system and all clusters within it. - -- **Standard User:** - - These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters. - ->**Note:** You cannot create, update, or delete Global Permissions. - -#### Global Permission Assignment - -Assignment of global permissions to a user depends on their authentication source: external or local. - -- **External Authentication** - - When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the `Standard User` global permission. - -- **Local Authentication** - - When you create a new local user, you assign them a global permission as you complete the **Add User** form. - -#### Custom Global Permissions - -Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a custom set of permissions. - -_Permissions_ are individual access rights that you can assign when selecting a custom permission for a user. - -Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. See the [table below](#global-permissions-reference) for a list of individual permissions available. - -#### Global Permissions Reference - -The following table lists each custom global permission available and whether it is assigned to the default global permissions, `Administrator` and `Standard User`. - -| Custom Global Permission | Administrator | Standard User | -| ---------------------------------- | ------------- | ------------- | -| Manage Authentication | ✓ | | -| Manage Catalogs | ✓ | | -| Manage Node Drivers | ✓ | | -| Manage PodSecurityPolicy Templates | ✓ | | -| Manage Roles | ✓ | | -| Manage Users | ✓ | | -| Create Clusters | ✓ | ✓ | -| User Catalog Templates | ✓ | ✓ | -| Login Access | ✓ | ✓ | - -> **Note:** 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`. - -### Cluster and Project Roles - -Cluster and project roles define user authorization inside a cluster or project. You can manage these roles from the **Global > Security > Roles** page. From this page you can: - -- Create and manage new roles for use across all clusters and projects -- [Lock/unlock roles](#locked-roles) so that they may not be used in any new role assignments (existing assignments will still be enforced). - - -#### 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 user 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`. - -- **Owner:** - - These users have full control over the cluster and all resources in it. - -- **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 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 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 in Rancher and whether it is also granted by the `Owner` or `Member` role. - -| Custom Cluster Role | Owner | Member | -| ---------------------------------- | ------------- | ------------- | -| Manage Cluster Members | ✓ | | -| Manage Nodes | ✓ | | -| Manage Storage | ✓ | | -| View All Projects | ✓ | | -| Create Project | ✓ | ✓ | -| View Cluster Members | ✓ | ✓ | -| View Nodes | ✓ | ✓ | - -> **Note:** Each cluster role listed above, including `Owner` and `Member`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page. - -#### 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`. - -- **Owner:** - - These users have full control over the project and all resources in it. - -- **Member:** - - These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members. - -- **Read Only:** - - These users can view everything in the project but cannot create, update, or delete anything. - -##### Custom Project Roles - -Rancher lets you assign _custom project roles_ to a 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 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. - -| Custom Cluster Role | Owner | Member | Read Only | -| ---------------------------------- | ------------- | ------------- | ------------- | -| Manage Project Members | ✓ | | | -| Create Namespaces | ✓ | ✓ | | -| Manage Config Maps | ✓ | ✓ | | -| Manage Ingress | ✓ | ✓ | | -| Manage Secrets | ✓ | ✓ | | -| Manage Service Accounts | ✓ | ✓ | | -| Manage Services | ✓ | ✓ | | -| Manage Volumes | ✓ | ✓ | | -| Manage Workloads | ✓ | ✓ | | -| View Config Maps | ✓ | ✓ | ✓ | -| View Ingress | ✓ | ✓ | ✓ | -| View Project Members | ✓ | ✓ | ✓ | -| View Secrets | ✓ | ✓ | ✓ | -| View Service Accounts | ✓ | ✓ | ✓ | -| View Services | ✓ | ✓ | ✓ | -| View Volumes | ✓ | ✓ | ✓ | -| View Workloads | ✓ | ✓ | ✓ | - -> **Note:** 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. - -### 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. - -#### Locked Roles - -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. - diff --git a/content/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/_index.md new file mode 100644 index 00000000000..6f742877568 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/_index.md @@ -0,0 +1,97 @@ +--- +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 user 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`. + +- **Owner:** + + These users have full control over the cluster and all resources in it. + +- **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 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 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 in Rancher and whether it is also granted by the `Owner` or `Member` role. + +| Custom Cluster Role | Owner | Member | +| ---------------------------------- | ------------- | ------------- | +| Manage Cluster Members | ✓ | | +| Manage Nodes | ✓ | | +| Manage Storage | ✓ | | +| View All Projects | ✓ | | +| Create Project | ✓ | ✓ | +| View Cluster Members | ✓ | ✓ | +| View Nodes | ✓ | ✓ | + +> **Note:** Each cluster role listed above, including `Owner` and `Member`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page. + +### 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`. + +- **Owner:** + + These users have full control over the project and all resources in it. + +- **Member:** + + These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members. + +- **Read Only:** + + These users can view everything in the project but cannot create, update, or delete anything. + +#### Custom Project Roles + +Rancher lets you assign _custom project roles_ to a 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 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. + +| Custom Cluster Role | Owner | Member | Read Only | +| ---------------------------------- | ------------- | ------------- | ------------- | +| Manage Project Members | ✓ | | | +| Create Namespaces | ✓ | ✓ | | +| Manage Config Maps | ✓ | ✓ | | +| Manage Ingress | ✓ | ✓ | | +| Manage Secrets | ✓ | ✓ | | +| Manage Service Accounts | ✓ | ✓ | | +| Manage Services | ✓ | ✓ | | +| Manage Volumes | ✓ | ✓ | | +| Manage Workloads | ✓ | ✓ | | +| View Config Maps | ✓ | ✓ | ✓ | +| View Ingress | ✓ | ✓ | ✓ | +| View Project Members | ✓ | ✓ | ✓ | +| View Secrets | ✓ | ✓ | ✓ | +| View Service Accounts | ✓ | ✓ | ✓ | +| View Services | ✓ | ✓ | ✓ | +| View Volumes | ✓ | ✓ | ✓ | +| View Workloads | ✓ | ✓ | ✓ | + +> **Note:** 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. + +### 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. diff --git a/content/rancher/v2.x/en/admin-settings/rbac/creating-roles/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md similarity index 59% rename from content/rancher/v2.x/en/admin-settings/rbac/creating-roles/_index.md rename to content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md index 13defa7d559..45bae9fcb9d 100644 --- a/content/rancher/v2.x/en/admin-settings/rbac/creating-roles/_index.md +++ b/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md @@ -1,8 +1,8 @@ --- -title: Creating Roles -weight: 25 +title: Custom Roles +weight: 1128 aliases: - -/rancher/v2.x/en/tasks/global-configuration/roles/ + - /rancher/v2.x/en/tasks/global-configuration/roles/ --- Within Rancher, _roles_ determine what actions a user can make within a cluster or project. @@ -13,12 +13,12 @@ Note that _roles_ are different from _permissions_, which determine what cluster > >To complete the tasks on this page, the following permissions are required: > ->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#global-permissions). ->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#custom-global-permissions) with the [Manage Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#global-permissions-reference) role assigned. +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/). +>- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. ## Adding A Custom Role -While Rancher comes out-of-the-box with a set of default user roles, you can also create custom roles to provide users with very specific permissions within Rancher. +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. 1. From the **Global** view, select **Security > Roles** from the main menu. @@ -26,7 +26,7 @@ While Rancher comes out-of-the-box with a set of default user roles, you can als 3. **Name** the role. -4. Choose whether to set the role to a status of [locked]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#locked-roles). +4. Choose whether to set the role to a status of [locked]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/). Locked roles cannot be assigned to users. @@ -51,19 +51,3 @@ While Rancher comes out-of-the-box with a set of default user roles, you can als 7. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. 8. Click **Create**. - -## Locking/Unlocking Roles - -If you want to prevent a role from being assigned to users, you can set it to a status of `locked`. For more information about what this status means, see [Locked Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#locked-roles). - -You can lock roles in two contexts: - -- When you're [adding a custom role](#adding-a-custom-role). -- 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 **Vertical Ellipsis (...)** > **Edit**. - -3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**. diff --git a/content/rancher/v2.x/en/admin-settings/rbac/global-permissions/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/global-permissions/_index.md new file mode 100644 index 00000000000..931993237c2 --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/rbac/global-permissions/_index.md @@ -0,0 +1,54 @@ +--- +title: Global Permissions +weight: 1126 +--- + +Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are two default global permissions: `Administrator` and `Standard User`. + +- **Administrator:** + + These users have full control over the entire Rancher system and all clusters within it. + +- **Standard User:** + + These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters. + +>**Note:** You cannot create, update, or delete Global Permissions. + +### Global Permission Assignment + +Assignment of global permissions to a user depends on their authentication source: external or local. + +- **External Authentication** + + When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the `Standard User` global permission. + +- **Local Authentication** + + When you create a new local user, you assign them a global permission as you complete the **Add User** form. + +### Custom Global Permissions + +Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a custom set of permissions. + +_Permissions_ are individual access rights that you can assign when selecting a custom permission for a user. + +Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. See the [table below](#global-permissions-reference) for a list of individual permissions available. + +### Global Permissions Reference + +The following table lists each custom global permission available and whether it is assigned to the default global permissions, `Administrator` and `Standard User`. + +| Custom Global Permission | Administrator | Standard User | +| ---------------------------------- | ------------- | ------------- | +| Manage Authentication | ✓ | | +| Manage Catalogs | ✓ | | +| Manage Node Drivers | ✓ | | +| Manage PodSecurityPolicy Templates | ✓ | | +| Manage Roles | ✓ | | +| Manage Users | ✓ | | +| Create Clusters | ✓ | ✓ | +| User Catalog Templates | ✓ | ✓ | +| Login Access | ✓ | ✓ | + +> **Note:** 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`. diff --git a/content/rancher/v2.x/en/admin-settings/rbac/locked-roles/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/locked-roles/_index.md new file mode 100644 index 00000000000..d3e61d8b2ea --- /dev/null +++ b/content/rancher/v2.x/en/admin-settings/rbac/locked-roles/_index.md @@ -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](({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). +- When you editing an existing role (see below). + +1. From the **Global** view, select **Security** > **Roles**. + +2. From the role that you want to lock (or unlock), select **Vertical Ellipsis (...)** > **Edit**. + +3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**. diff --git a/content/rancher/v2.x/en/admin-settings/rancher-server-url/_index.md b/content/rancher/v2.x/en/admin-settings/server-url/_index.md similarity index 84% rename from content/rancher/v2.x/en/admin-settings/rancher-server-url/_index.md rename to content/rancher/v2.x/en/admin-settings/server-url/_index.md index ffdc30ac506..795d04931ee 100644 --- a/content/rancher/v2.x/en/admin-settings/rancher-server-url/_index.md +++ b/content/rancher/v2.x/en/admin-settings/server-url/_index.md @@ -1,9 +1,9 @@ --- title: Rancher Server URL -weight: 25 +weight: 1105 aliases: - -/rancher/v2.x/en/concepts/global-configuration/server-url - -/rancher/v2.x/en/tasks/global-configuration/server-url + - /rancher/v2.x/en/concepts/global-configuration/server-url/ + - /rancher/v2.x/en/tasks/global-configuration/server-url/ --- This is the URL of your Rancher Server. All nodes in your cluster must resolve to this URL. diff --git a/content/rancher/v2.x/en/catalog-and-charts/_index.md b/content/rancher/v2.x/en/catalog-and-charts/_index.md deleted file mode 100644 index 4c71d9eeb3d..00000000000 --- a/content/rancher/v2.x/en/catalog-and-charts/_index.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Catalogs and Charts -weight: 4000 -aliases: - - /rancher/v2.x/en/concepts/global-configuration/catalog/ - - /rancher/v2.x/en/tasks/global-configuration/catalog/ ---- - -This section includes step-by-step instruction on how to configure default and custom catalogs. - -- [Enabling Default Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/enabling-default-catalogs) -- [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs) -- [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/customizing-charts) - - -_Catalogs_ are GitHub repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _charts_. - -_Charts_ are a packaging format popularized by [Helm](https://docs.helm.sh/). Think of them as templates for deployments. Per Helm, charts are: - ->A collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. - -Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. - -## Catalog Types - -Within Rancher, you can access several different catalogs either by default or through customization. Enable or disable these catalogs by opening the **Global** view and then selecting **Catalogs** from the main menu. - -- **Library** - - The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.0, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. - - This catalog features Rancher Charts, which include some [notable advantages](#chart-types) over native Helm charts. - -- **Helm Stable** - - This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps. - -- **Helm Incubator** - - Similar in user experience to Helm Stable, but this catalog is filled with applications in BETA. - -- **Custom** - - Finally, you have the option of building your own catalogs. Custom catalogs are useful when you have a handful of apps that you deploy regularly in a specific configuration. - -### Custom Catalog Creation - -Creating a custom catalog for Rancher is straightforward. Create a Git repo and then direct Rancher toward the repo. - -Custom catalog requirements include: - -- A unique name. -- A URL that `git clone` can handle. - -For step-by-step directions, see [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs). - -When you're done creating the catalog, populate it with charts. Custom catalogs can support both native Helm charts and Rancher charts. See [Custom Chart Creation](#custom-chart-creation). - -## Chart Types - -Rancher supports two different types of charts: - -- **Helm Charts** - - Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you'll learn the chart's parameters and then configure them using **Answers**, which are sets of key value pairs. - - The Helm Stable and Helm Incubators are populated with native Helm charts. However, you can also use native Helm charts in Custom catalogs (although we recommend Rancher Charts). - -- **Rancher Charts** - - Rancher charts mirror native helm charts, although they add two files that enhance user experience: `app-readme.md` and `questions.yaml`. Read more about them in [Rancher Chart Additional Files](#rancher-chart-additional-files). - - Advantages of Rancher charts include: - - - **Enhanced Revision Tracking** - - While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart. - - - **Streamlined Application Launch** - - Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application. - - - **Application Resource Management** - - Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. - -### Chart Directory Structure - -The following table demonstrates the directory structure for a chart, which can be found in a chart directory: `charts/%application%/%app version%/`. This information is helpful when customizing charts for a custom catalog. Files denoted with **Rancher Specific** are specific to Rancher charts, but are optional for chart customization. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Sub-Directory FileDescription
app-readme.md Rancher Specific: Text displayed in the charts header within the Rancher UI.
charts/Directory containing dependency charts.
Chart.ymlRequired Helm chart information file.
questions.ymlRancher Specific: File containing form questions displayed within the Rancher UI. Questions display in Configuration Options.
README.mdOptional: Helm Readme file displayed within Rancher UI. This test displays in Detailed Descriptions.
requirements.ymlOptional YAML file listing dependencies for the chart.
templates/A directory of templates that, when combined with values.yml, generates Kubernetes YAML.
values.ymlThe default configuration values for the chart.
- -### Rancher Chart Additional Files - -Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not. - -- `app-readme.md` - - A file that provides descriptive text in the chart's UI header. The following image displays the difference between a Rancher chart (which includes `app-readme.md`) and a native Helm chart (which does not). - - Rancher Chart with app-readme.md (left) vs. Helm Chart without (right) - - ![app-readme.md]({{< baseurl >}}/img/rancher/app-readme.png) - -- `questions.yml` - - A file that contains questions for a form. These form questions simplify deployment of a chart. Without it, you must configure the deployment using key value pairs, which is more difficult. The following image displays the difference between a Rancher chart (which includes `questions.yml`) and a native Helm chart (which does not). - - - Rancher Chart with question.yml (left) vs. Helm Chart without (right) - - ![questions.yml]({{< baseurl >}}/img/rancher/questions.png) - - -### Custom Chart Creation - - You can fill your custom catalogs with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience. - - For information on how to add and customize charts for a custom catalog, see [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/customizing-charts). - ->**Note:** For a complete walkthrough of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/). diff --git a/content/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs/_index.md b/content/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs/_index.md deleted file mode 100644 index 6a2d95e72b6..00000000000 --- a/content/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs/_index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Adding Custom Catalogs -weight: 4015 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/ ---- - -You can create custom catalogs of charts for use in Rancher. Custom catalogs are helpful for fast deployment of applications unique to your environment. - ->**Notes:** -> ->- Currently, you can only add custom catalogs to Rancher at the global level. Therefore, any catalog that you add is shared with all clusters and projects. -> ->- Currently, only unauthenticated catalogs are supported. -
-
- ->**Prerequisites:** -> ->- Recommended: Read [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs). ->- Create a GitHub repository to serve as your custom catalog. - - -1. From the **Global** view, choose **Catalogs** from the main menu. -2. Click **Add Catalog**. -3. Complete the form and click **Create**. - -**Result**: Your catalog is added to Rancher. - -## What's Next? - -Add native Helm charts, Rancher charts, or both to your repository. For more information, see [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/customizing-charts/). diff --git a/content/rancher/v2.x/en/catalog-and-charts/customizing-charts/_index.md b/content/rancher/v2.x/en/catalog-and-charts/customizing-charts/_index.md deleted file mode 100644 index a72c0eb5ab4..00000000000 --- a/content/rancher/v2.x/en/catalog-and-charts/customizing-charts/_index.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Customizing Charts -weight: 4020 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts/ ---- - -Before you can deploy customized catalog apps using Rancher, you must add charts to the GitHub repository serving as your custom catalog. - -The custom catalog can contain native Helm charts, Rancher charts, or a combination of both (although we recommend using Rancher charts). - ->**Prerequisites:** - ->- Recommended: Read [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs). ->- Create a GitHub repository to serve as your custom catalog. ->- Complete [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs). - ->**Note:** Customization of Helm charts takes place outside of the Rancher UI. - -1. Within the GitHub repo that you're using as your custom catalog, create a directory structure that mirrors the structure listed in [Chart Directory Structure]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#chart-directory-structure). - - Rancher requires this directory structure, although `app-readme.md` and `questions.yml` are optional. - - >**Tip:** - > - >- To begin customizing a chart, copy one from either the [Rancher Library](https://github.com/rancher/charts) or the [Helm Stable](https://github.com/kubernetes/charts/tree/master/stable). - >- For a complete walk through of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/). - -2. **Recommended:** Create an `app-readme.md` file. - - Use this file to create custom text for your chart's header in the Rancher UI. You can use this text to notify users that the chart is customized for your environment or provide special instruction on how to use it. -
-
- **Example**: - - ``` - $ cat ./app-readme.md - - # Wordpress ROCKS! - ``` - -3. **Recommended:** Create a `questions.yml` file. - - This file creates a form for users to specify deployment parameters when they deploy the custom chart. Without this file, users **must** specify the parameters manually using key value pairs, which isn't user-friendly. -
-
- The example below creates a form that prompts users for persistent volume size and a storage class. -
-
- For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](#question-variable-reference). - - 
-        categories:
-        - Blog
-        - CMS
-        questions:
-        - variable: persistence.enabled
-        default: "false"
-        description: "Enable persistent volume for WordPress"
-        type: boolean
-        required: true
-        label: WordPress Persistent Volume Enabled
-        show_subquestion_if: true
-        group: "WordPress Settings"
-        subquestions:
-        - variable: persistence.size
-            default: "10Gi"
-            description: "WordPress Persistent Volume Size"
-            type: string
-            label: WordPress Volume Size
-        - variable: persistence.storageClass
-            default: ""
-            description: "If undefined or null, uses the default StorageClass. Default to null"
-            type: storageclass
-            label: Default StorageClass for WordPress
-
- -4. Check the customized chart into your GitHub repo. - -**Result:** Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes. - -## What's Next? - -Launch your custom catalog app. For more information, see [Launching a Catalog App]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/launch-a-catalog-app). - -## Question Variable Reference - -This reference contains variables that you can use in `questions.yml`. - -| Variable | Type | Required | Description | -| ------------- | ------------- | --- |------------- | -| variable | string | true | Define the variable name specified in the `values.yml` file, using `foo.bar` for nested objects. | -| label | string | true | Define the UI label. | -| description | string | false | Specify the description of the variable.| -| type | string | false | Default to `string` if not specified (current supported types are string, boolean, int, enum, password, storageclass and hostname).| -| required | bool | false | Define if the variable is required or not (true \| false)| -| default | string | false | Specify the default value. | -| group | string | false | Group questions by input value. | -| min_length | int | false | Min character length.| -| max_length | int | false | Max character length.| -| min | int | false | Min integer length. | -| max | int | false | Max integer length. | -| options | []string | false | Specify the options when the variable type is `enum`, for example: options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer"| -| valid_chars | string | false | Regular expression for input chars validation. | -| invalid_chars | string | false | Regular expression for invalid input chars validation.| -| subquestions | []subquestion | false| Add an array of subquestions.| -| show_if | string | false | Show current variable if conditional variable is true. For example `show_if: "serviceType=Nodeport"` | -| show\_subquestion_if | string | false | Show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| - ->**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. diff --git a/content/rancher/v2.x/en/catalog-and-charts/enabling-default-catalogs/_index.md b/content/rancher/v2.x/en/catalog-and-charts/enabling-default-catalogs/_index.md deleted file mode 100644 index d0c1b1c6f90..00000000000 --- a/content/rancher/v2.x/en/catalog-and-charts/enabling-default-catalogs/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Enabling Default Catalogs -weight: 4005 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/ ---- - -Out-of-the-box, you can enable several different catalog repositories to simplify deployment of applications. - -1. From the **Global** view, choose **Catalogs** from the main menu. -2. Toggle the default catalogs that you want use to a setting of **Enabled**. The [default catalogs]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#catalog-types) are: - - - **Library** - - **Helm Stable** - - **Helm Incubator** - - >**Note:** If you want to use a custom catalog, see [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog-and-charts/adding-custom-catalogs) instead of this topic. - -**Result:** The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Catalog Apps** from the main menu. - -## What's Next? - -Deploy catalog applications to your cluster nodes. For more information, see [Launching a Catalog App]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/launch-a-catalog-app). diff --git a/content/rancher/v2.x/en/catalog-and-charts/launching-catalog-apps/_index.md b/content/rancher/v2.x/en/catalog-and-charts/launching-catalog-apps/_index.md deleted file mode 100644 index 6d1645d43e7..00000000000 --- a/content/rancher/v2.x/en/catalog-and-charts/launching-catalog-apps/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Launching Catalog Applications -weight: 4010 ---- diff --git a/content/rancher/v2.x/en/catalog/_index.md b/content/rancher/v2.x/en/catalog/_index.md new file mode 100644 index 00000000000..d7e17fca250 --- /dev/null +++ b/content/rancher/v2.x/en/catalog/_index.md @@ -0,0 +1,97 @@ +--- +title: Catalogs and Charts +weight: 4000 +aliases: + - /rancher/v2.x/en/concepts/global-configuration/catalog/ + - /rancher/v2.x/en/concepts/catalogs/ + - /rancher/v2.x/en/tasks/global-configuration/catalog/ + - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/ + - /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/ +--- + +Rancher provides a catalog of charts that make it easy to repeatedly deploy any applications. + +_Catalogs_ are GitHub repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _charts_. + +_Charts_ are a packaging format popularized by [Helm](https://docs.helm.sh/). Think of them as templates for deployments. Per Helm, charts are: + +>A collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. + +Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. + +## Enabling Built-in Catalogs + +Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. + +1. From the **Global** view, choose **Catalogs** from the main menu. +2. Toggle the default catalogs that you want use to a setting of **Enabled**. + + - **Library** + + The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.0, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. + + This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts. + + - **Helm Stable** + + This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps. + + - **Helm Incubator** + + Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**. + + **Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Catalog Apps** from the main menu. + +## Adding Custom Catalogs + +Adding a catalog is as simple as adding a catalog name, a URL and a branch name. The URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately. + +>**Notes:** +> +>- Currently, you can only add custom catalogs to Rancher at the global level. Therefore, any catalog that you add is shared with all clusters and projects. +> +>- Currently, only unauthenticated catalogs are supported. +
+
+ + + + 1. From the **Global** view, choose **Catalogs** from the main menu. + 2. Click **Add Catalog**. + 3. Complete the form and click **Create**. + + **Result**: Your catalog is added to Rancher. + +## Launching Catalog Applications + +After you've either enabled the built-in catalogs or added your own custom catalog, you can start launching any catalog application. + +1. From the **Global** view, open the project that you want to deploy to. + +2. From the main menu, choose **Catalog Apps**. Then click **Launch**. + +3. Find the app that you want to launch, and then click **View Now**. + +4. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application. + + * If you would like to change the **Namespace**, click **Customize** and enter a new name. + * If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list. + +5. Select a **Template Version**. + +6. Complete the rest of the **Configuration Options**. + + * For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section. + * Keys and values are available within **Detailed Descriptions**. + +7. Review the files in **Preview**. When you're satisfied, click **Launch**. + +**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's: + +- **Workloads** view +- **Catalog Apps** view diff --git a/content/rancher/v2.x/en/catalog/custom/_index.md b/content/rancher/v2.x/en/catalog/custom/_index.md new file mode 100644 index 00000000000..9a0904d4c9d --- /dev/null +++ b/content/rancher/v2.x/en/catalog/custom/_index.md @@ -0,0 +1,206 @@ +--- +title: Custom Catalogs and Charts +weight: 4020 +aliases: + - /rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts/ +--- + +Rancher's catalog service requires any custom catalogs to be structured in a specific format for the catalog service to be able to leverage it in Rancher. Any custom catalog must be a public Git repository. The URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. + +## Chart Types + +Rancher supports two different types of charts: + +- **Helm Charts** + + Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you'll learn the chart's parameters and then configure them using **Answers**, which are sets of key value pairs. + + The Helm Stable and Helm Incubators are populated with native Helm charts. However, you can also use native Helm charts in Custom catalogs (although we recommend Rancher Charts). + +- **Rancher Charts** + + Rancher charts mirror native helm charts, although they add two files that enhance user experience: `app-readme.md` and `questions.yaml`. Read more about them in [Rancher Chart Additional Files](#rancher-chart-additional-files). + + Advantages of Rancher charts include: + + - **Enhanced Revision Tracking** + + While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart. + + - **Streamlined Application Launch** + + Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application. + + - **Application Resource Management** + + Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. + +## Chart Directory Structure + +The following table demonstrates the directory structure for a chart, which can be found in a chart directory: `charts/%application%/%app version%/`. This information is helpful when customizing charts for a custom catalog. Files denoted with **Rancher Specific** are specific to Rancher charts, but are optional for chart customization. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-Directory FileDescription
app-readme.md Rancher Specific: Text displayed in the charts header within the Rancher UI.
charts/Directory containing dependency charts.
Chart.ymlRequired Helm chart information file.
questions.ymlRancher Specific: File containing form questions displayed within the Rancher UI. Questions display in Configuration Options.
README.mdOptional: Helm Readme file displayed within Rancher UI. This test displays in Detailed Descriptions.
requirements.ymlOptional YAML file listing dependencies for the chart.
templates/A directory of templates that, when combined with values.yml, generates Kubernetes YAML.
values.ymlThe default configuration values for the chart.
+ +## Rancher Chart Additional Files + +Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not. + +- `app-readme.md` + + A file that provides descriptive text in the chart's UI header. The following image displays the difference between a Rancher chart (which includes `app-readme.md`) and a native Helm chart (which does not). + + Rancher Chart with app-readme.md (left) vs. Helm Chart without (right) + + ![app-readme.md]({{< baseurl >}}/img/rancher/app-readme.png) + +- `questions.yml` + + A file that contains questions for a form. These form questions simplify deployment of a chart. Without it, you must configure the deployment using key value pairs, which is more difficult. The following image displays the difference between a Rancher chart (which includes `questions.yml`) and a native Helm chart (which does not). + + + Rancher Chart with question.yml (left) vs. Helm Chart without (right) + + ![questions.yml]({{< baseurl >}}/img/rancher/questions.png) + + +### Question Variable Reference + +This reference contains variables that you can use in `questions.yml`. + +| Variable | Type | Required | Description | +| ------------- | ------------- | --- |------------- | +| variable | string | true | Define the variable name specified in the `values.yml` file, using `foo.bar` for nested objects. | +| label | string | true | Define the UI label. | +| description | string | false | Specify the description of the variable.| +| type | string | false | Default to `string` if not specified (current supported types are string, boolean, int, enum, password, storageclass and hostname).| +| required | bool | false | Define if the variable is required or not (true \| false)| +| default | string | false | Specify the default value. | +| group | string | false | Group questions by input value. | +| min_length | int | false | Min character length.| +| max_length | int | false | Max character length.| +| min | int | false | Min integer length. | +| max | int | false | Max integer length. | +| options | []string | false | Specify the options when the variable type is `enum`, for example: options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer"| +| valid_chars | string | false | Regular expression for input chars validation. | +| invalid_chars | string | false | Regular expression for invalid input chars validation.| +| subquestions | []subquestion | false| Add an array of subquestions.| +| show_if | string | false | Show current variable if conditional variable is true. For example `show_if: "serviceType=Nodeport"` | +| show\_subquestion_if | string | false | Show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| + +>**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. + + +## Example Custom Chart Creation + + You can fill your custom catalogs with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience. + +>**Note:** For a complete walkthrough of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/). + +1. Within the GitHub repo that you're using as your custom catalog, create a directory structure that mirrors the structure listed in [Chart Directory Structure](#chart-directory-structure). + + Rancher requires this directory structure, although `app-readme.md` and `questions.yml` are optional. + + >**Tip:** + > + >- To begin customizing a chart, copy one from either the [Rancher Library](https://github.com/rancher/charts) or the [Helm Stable](https://github.com/kubernetes/charts/tree/master/stable). + >- For a complete walk through of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/). + +2. **Recommended:** Create an `app-readme.md` file. + + Use this file to create custom text for your chart's header in the Rancher UI. You can use this text to notify users that the chart is customized for your environment or provide special instruction on how to use it. +
+
+ **Example**: + + ``` + $ cat ./app-readme.md + + # Wordpress ROCKS! + ``` + +3. **Recommended:** Create a `questions.yml` file. + + This file creates a form for users to specify deployment parameters when they deploy the custom chart. Without this file, users **must** specify the parameters manually using key value pairs, which isn't user-friendly. +
+
+ The example below creates a form that prompts users for persistent volume size and a storage class. +
+
+ For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](#question-variable-reference). + + 
+        categories:
+        - Blog
+        - CMS
+        questions:
+        - variable: persistence.enabled
+        default: "false"
+        description: "Enable persistent volume for WordPress"
+        type: boolean
+        required: true
+        label: WordPress Persistent Volume Enabled
+        show_subquestion_if: true
+        group: "WordPress Settings"
+        subquestions:
+        - variable: persistence.size
+            default: "10Gi"
+            description: "WordPress Persistent Volume Size"
+            type: string
+            label: WordPress Volume Size
+        - variable: persistence.storageClass
+            default: ""
+            description: "If undefined or null, uses the default StorageClass. Default to null"
+            type: storageclass
+            label: Default StorageClass for WordPress
+
+ +4. Check the customized chart into your GitHub repo. + +**Result:** Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes. diff --git a/content/rancher/v2.x/en/cli/_index.md b/content/rancher/v2.x/en/cli/_index.md index c8876b2e9b4..9e1d58a2dfb 100644 --- a/content/rancher/v2.x/en/cli/_index.md +++ b/content/rancher/v2.x/en/cli/_index.md @@ -15,7 +15,7 @@ The binary can be downloaded directly from the UI. The link can be found in the After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires: -- Your [Rancher Server URL]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/server-url), which is used to connect to Rancher Server. +- Your [Rancher Server URL]({{< baseurl >}}/rancher/v2.x/en/admin-settings/server-url), which is used to connect to Rancher Server. - An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key]({{< baseurl >}}/rancher/v2.x/en/user-settings/api-keys/). ### CLI Authentication @@ -30,7 +30,7 @@ If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to con ### Project Selection -Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project]({{< baseurl >}}/rancher/v2.x/en/concepts/projects/) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project. +Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project. **Example: `./rancher context switch` Output** ``` @@ -56,23 +56,23 @@ The following commands are available for use in Rancher CLI. - `apps, [app]` - Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or [Rancher charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#rancher-chart-structure)). + Performs operations on catalog applications (i.e. individual [Helm charts](https://docs.helm.sh/developing_charts/) or [Rancher charts]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-directory-structure)). - `catalog` - Performs operations on [catalogs]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs). + Performs operations on [catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/). - `clusters, [cluster]` - Performs operations on your [clusters]({{< baseurl >}}/rancher/v2.x/en/clusters/). + Performs operations on your [clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/). - `context` - Switches between Rancher [projects]({{< baseurl >}}/rancher/v2.x/en/concepts/projects). For an example, see [Project Selection](#project-selection). + Switches between Rancher [projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/). For an example, see [Project Selection](#project-selection). - `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` - Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{< baseurl >}}/rancher/v2.x/en/concepts/projects) and [workloads]({{< baseurl >}}/rancher/v2.x/en/concepts/workloads)). Specify resources by name or ID. + Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/) and [workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/)). Specify resources by name or ID. - `kubectl` @@ -84,7 +84,7 @@ The following commands are available for use in Rancher CLI. - `namespaces, [namespace]` - Performs operations on [namespaces]({{< baseurl >}}/rancher/v2.x/en/concepts/projects/#namespaces). + Performs operations on [namespaces]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/#namespaces). - `nodes, [node]` @@ -92,11 +92,11 @@ The following commands are available for use in Rancher CLI. - `projects, [project]` - Performs operations on [projects]({{< baseurl >}}/rancher/v2.x/en/concepts/projects). + Performs operations on [projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/). - `ps` - Displays [workloads]({{< baseurl >}}/rancher/v2.x/en/concepts/workloads) in a project. + Displays [workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads) in a project. - `settings, [setting]` diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md new file mode 100644 index 00000000000..ac13086c58e --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -0,0 +1,89 @@ +--- +title: Provisioning Kubernetes Clusters +weight: 2000 +aliases: + - /rancher/v2.x/en/concepts/clusters/ + - /rancher/v2.x/en/concepts/clusters/cluster-providers/ + - /rancher/v2.x/en/tasks/clusters/ + - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/ +--- + +## What's a Kubernetes Cluster? + +In the IT world, a cluster is a group of computing resources that work as a team to accomplish a goal. + +A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations. Kubernetes reduces the manual processes of maintaining organization operations. + +### Kubernetes Cluster Node Components + +Each computing resource in a Kubernetes Cluster is called a _node_. Node can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three distinct types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes. Understanding the role of each node will help you create your own Kubernetes cluster. + +#### etcd Nodes + +[etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd) nodes run the `etcd` database. The `etcd` database component is a key value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. + +`etcd` is a distributed key value store, meaning it runs on multiple nodes so that there's always a backup available for fail over. Even though you can run `etcd` on a single node, you should run it on multiple nodes. We recommend 3, 5, or 7 nodes for redundancy. + +#### Control Plane Nodes + +[Control plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your Kubernetes cluster is running according to your configuration. Because all cluster data is stored on your `etcd` nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, you can a single node can share the control plane and `etcd` roles. + +#### Worker Nodes + +[Worker nodes](https://kubernetes.io/docs/concepts/architecture/nodes/) run: + +- _Kubelets_: An agent that monitors the state of the node, ensuring your containers are healthy. +- _Workloads_: The containers and pods that hold your apps, as well as other types of deployments. + +Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as needed for your workload needs. + +## Cluster Creation in Rancher + +Now that you know what a Kubernetes Cluster is, how does Rancher fit in? + +Rancher simplifies creation of Kubernetes clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a Kubernetes cluster. Use the option that best fits you use case. + +## Cluster Creation Options + +Options include: + + + +- [Hosted Kubernetes Cluster](#hosted-kubernetes-cluster) +- [Rancher Launched Kubernetes](#rancher-launched-kubernetes) + + - [Node Pools](#node-pools) + - [Custom Nodes](#custom-nodes) +- [Import Existing Cluster](#import-existing-cluster) + + + +### Hosted Kubernetes Cluster + +If you already use a Kubernetes provider such as Google GKE, Rancher can integrate with its cloud APIs, allowing you to create and manage your hosted cluster from the Rancher UI. + +[Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) + +### Rancher Launched Kubernetes + +Alternatively, you can use Rancher to create the Kubernetes cluster on your own nodes, using [Rancher Kubernetes Engine (RKE)]({{< baseurl >}}/rke/v0.1.x/en/). RKE is Rancher’s own lightweight Kubernetes installer. With these clusters, Rancher manages the deployment of Kubernetes. These Kubernetes clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. These nodes can either be provisioned through Rancher's UI, which calls [Docker Machine](https://docs.docker.com/machine/) to launch nodes on various cloud providers or they can be existing nodes that users bring and run a Rancher agent container onto. + +[Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) + +#### Node Pools + +Using Rancher, you can create pools of nodes based on a [node template]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your cloud providers. The available cloud providers to create a node template are decided based on active [node drivers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers). The benefit of using a node pool is that if a node loses connectivity with the cluster, Rancher will automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +[Node Pools]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) + +#### Custom Nodes + +You can bring any nodes you want to Rancher and have Rancher create the Kubernetes cluster. These nodes can include on-premise bare metal servers, nodes existing in a cloud provider or virtual machines. + +[Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) + +### Import Existing Cluster + +Users can import an existing Kubernetes cluster into Rancher. Rancher does not automate the provisioning, scaling, and upgrade of imported Kubernetes clusters. All other cluster management, policy management, and workload management capabilities of Rancher apply to imported clusters. + +[Importing Existing Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) diff --git a/content/rancher/v2.x/en/cluster-provisioning/cluster-members/_index.md b/content/rancher/v2.x/en/cluster-provisioning/cluster-members/_index.md new file mode 100644 index 00000000000..9d627e0803f --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/cluster-members/_index.md @@ -0,0 +1,20 @@ +--- +title: Adding Users to Clusters +weight: 2500 +aliases: + - /rancher/v2.x/en/tasks/clusters/adding-managing-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]({{< baseurl >}}/rancher/v2.x/en/kubernetes-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]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/) + + You can always add members to a cluster after a cluster is provisioned. diff --git a/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md new file mode 100644 index 00000000000..0f6b7d9237e --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md @@ -0,0 +1,8 @@ +--- +title: Custom Cluster +weight: 2210 +--- + +If you don't want to host your Kubernetes cluster in a [hosted kubernetes provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) or provision nodes through Rancher, you can use the _custom cluster_ option to create a Kubernetes cluster in on-premise bare-metal servers, on-premise virtual machines, or in _any_ IaaS provider. + +In this scenario, you'll bring the nodes yourself, and then configure them to meet Rancher's [requirements]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/#requirements). Then, use the [Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) install option to setup your cluster. diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md new file mode 100644 index 00000000000..5c47482aae3 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md @@ -0,0 +1,22 @@ +--- +title: Hosted Kubernetes Providers +weight: 2100 +--- + +You can use Rancher to create clusters in a hosted Kubernetes provider, such as Google GKE. + +In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-premise or in an IaaS, all from the same UI. + +Rancher supports the following Kubernetes providers: + +- Google GKE (Google Container Engine) +- Amazon EKS (Elastic Container Service) +- Microsoft AKS (Azure Kubernetes Service) + +## Hosted Kubernetes Provider Authentication + +When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures: + +- [Creating a GKE Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke) +- [Creating an EKS Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks) +- [Creating an AKS Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks) \ No newline at end of file diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/_index.md new file mode 100644 index 00000000000..d19031d1d1c --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks/_index.md @@ -0,0 +1,43 @@ +--- +title: Creating an AKS Cluster +shortTitle: Azure Kubernetes Service +weight: 2115 +aliases: + - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service/ +--- + +You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS). + +## Prerequisites + +Obtain the following information from the Microsoft Azure Portal: + +- Your Subscription ID. +- Your Tenant ID. +- A Client ID and Client Secret. + + Complete Create Service Principal for Azure AD to obtain this information. + +## To Create an AKS Cluster + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Azure Kubernetes Service**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. Complete the **Account Access** form using the output from your Service Principal. This information is used to authenticate with Azure. + +7. Use **Nodes** to provision each node in your cluster and choose a geographical region. + + [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) +
+8. Click **Create**. +
+9. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/eks/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md similarity index 98% rename from content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/eks/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md index 62af862f0fc..f80f354049c 100644 --- a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/eks/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md @@ -3,7 +3,7 @@ title: Creating an EKS Cluster shortTitle: Amazon EKS weight: 2110 aliases: - - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-eks/_index.md + - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-eks/ --- ## Objectives diff --git a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/gke/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md similarity index 95% rename from content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/gke/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md index e0856d9c16a..e4622c0fc37 100644 --- a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/gke/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md @@ -3,11 +3,11 @@ title: Creating a GKE Cluster shortTitle: Google Container Engine weight: 2105 aliases: - - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-gke/_index.md + - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-gke/ --- ## Objectives -1. [Create a Service Account](#create-a-gke-service-account) +1. [Create a Service Account](#create-a-service-account) Begin by logging into Google Cloud Platform and creating a service account to operate your cluster. diff --git a/content/rancher/v2.x/en/clusters/imported-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md similarity index 100% rename from content/rancher/v2.x/en/clusters/imported-clusters/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md new file mode 100644 index 00000000000..8c8e39b8772 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md @@ -0,0 +1,20 @@ +--- +title: Rancher Launched Kubernetes +weight: 2200 +--- + +If you don't want to use a hosted Kubernetes provider, you can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses Rancher Kubernetes Engine]({{< baseurl >}}/rke/v0.1.x/en/) (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including: + +- Bare-metal servers +- On-premise virtual machines +- IaaS-hosted virtual machines + +RKE launched clusters are separated into two categories: + +- [Node Pools]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/): + + Using Rancher, you can create pools of nodes based on a [node template]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your cloud providers. The available cloud providers to create a node template are decided based on active [node drivers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers). The benefit of using a node pool is that if a node loses connectivity with the cluster, Rancher will automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +- [Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/): + + For use cases where you want to provision bare-metal servers, on-premise virtual machines, or bring virtual machines that are already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine. diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/custom-nodes/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md similarity index 74% rename from content/rancher/v2.x/en/clusters/rke-clusters/custom-nodes/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md index be0ff3a7f2f..d8d02e2aa06 100644 --- a/content/rancher/v2.x/en/clusters/rke-clusters/custom-nodes/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md @@ -6,7 +6,13 @@ aliases: - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-custom/ --- -## Objectives +## Custom Nodes + +Use Rancher to create a Kubernetes cluster on your on-premise bare metal servers. This option creates a cluster using a combination of Docker Machine and RKE, which is Rancher's own lightweight Kubernetes installer. In addition to bare metal servers, RKE can also create clusters on _any_ IaaS providers by integrating with node drivers. + +To use this option you'll need access to servers you intend to use as your Kubernetes cluster. Provision each server according to Rancher [requirements](#requirements), which includes some hardware specifications and Docker. After you install Docker on each server, run the command provided in the Rancher UI to turn each server into a Kubernetes node. + +## Objectives for Creating Cluster with Custom Nodes 1. [Provision a Linux Host](#provision-a-linux-host) @@ -28,23 +34,29 @@ Begin creation of a custom cluster by provisioning a Linux host. Your host can b - An on-premise VM - A bare-metal server +>**Bare-Metal Server Note:** +> +While creating your cluster, you must assign Kubernetes roles to your cluster nodes. If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). + Provision the host according to the requirements below. ### Requirements -{{< requirements_os >}} - -{{< requirements_hardware >}} - -{{< requirements_software >}} - -{{< requirements_ports_rancher >}} - -{{< requirements_ports_rke >}} - ->**Bare-Metal Server Note:** -> -While creating your cluster, you must assign Kubernetes roles to your cluster nodes. If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). +{{< accordion id="os" label="Operating System" >}} + {{< requirements_os >}} +{{< /accordion >}} +{{< accordion id="hardware" label="Hardware" >}} + {{< requirements_hardware >}} +{{< /accordion >}} +{{< accordion id="software" label="Software" >}} + {{< requirements_software >}} +{{< /accordion >}} +{{< accordion id="ports-rancher" label="Ports for Rancher" >}} + {{< requirements_ports_rancher >}} +{{< /accordion >}} +{{< accordion id="ports-rke" label="Ports for RKE" >}} + {{< requirements_ports_rke >}} +{{< /accordion >}} ## Create the Custom Cluster diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md new file mode 100644 index 00000000000..d3f067980c9 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md @@ -0,0 +1,51 @@ +--- +title: Nodes hosted in an Infrastructure Provider +weight: 2205 +aliases: + - /rancher/v2.x/en/concepts/global-configuration/node-drivers/ + - /rancher/v2.x/en/tasks/global-configuration/node-drivers/ + - /rancher/v2.x/en/concepts/global-configuration/node-templates/ +--- + +## Node Pools + +Using Rancher, you can create pools of nodes based on a [node template](#node-templates). The benefit of using a node pool is that if a node loses connectivity with the cluster, Rancher will automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +Each node pool is assigned with a [node component]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#node-components) to specify how these nodes should be configured for the Kubernetes cluster. + +## Node templates + +A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. Rancher provides a nice UI to be able to launch these nodes and uses [Docker Machine](https://docs.docker.com/machine/) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher. + +After you create a node template in Rancher, it's saved so that you can use this template again to create other node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile. + +## Node Drivers + +A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher. + +If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers. + +#### Managing Node Drivers + +>**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions: +> +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) +>- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. + +## Adding Custom Node Drivers + +If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add the provider's drivers in order to start using them to create node templates and eventually node pools. + +1. From the **Global** view, select **Node Drivers** from the main menu. + +2. Click **Add Node Driver**. + +3. Complete the **Add Node Driver** form. Then click **Create**. + +## Activating/Deactivating Node Drivers + +By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, Digital Ocean and vSphere. If you want to show or hide any node driver, you can change it's status. + +1. From the **Global** view, select **Node Drivers** from the main menu. + +2. Find the driver that you want to activate or deactivate and select **Vertical Elipsis (... ) > Edit**. Choose either **Activate** or **Deactivate**. diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/azure/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/azure/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/digital-ocean/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/digital-ocean/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md new file mode 100644 index 00000000000..132b4fb2110 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md @@ -0,0 +1,143 @@ +--- +title: Creating an Amazon EC2 Cluster +shortTitle: Amazon EC2 +weight: 2210 +aliases: + - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2/ +--- +Use {{< product >}} to create a Kubernetes cluster in Amazon EC2. + +1. From the **Clusters** page, click **Add Cluster**. +1. Choose **Amazon EC2**. +1. Enter a **Cluster Name**. +1. {{< step_create-cluster_member-roles >}} +1. {{< step_create-cluster_cluster-options >}}Refer to [Selecting Cloud Providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) to configure the Kubernetes Cloud Provider.

+1. {{< step_create-cluster_node-pools >}} +1. Click **Add Node Template**. + + + Complete each of the following forms using information available from the [EC2 Management Console](https://aws.amazon.com/ec2). + + * **Account Access** is there you configure the region of the nodes, and the credentials (Access Key and Secret Key) used to create the machine. + + [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey). + + See [Example Node IAM policy](#example-node-iam-policy) for an example policy that can be applied to these credentials. + - **Zone and Network** configures the availability zone and network settings for your cluster. + - **Security Groups** creates or configures the security groups applied to your nodes. + - **Instance** configures the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI. + + If you need to pass an **IAM Instance Profile Name** (not ARN), for example, when you want to use a [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers), you will need an additional permission in your policy. See [Example Node IAM policy with PassRole](#example-node-iam-policy-with-passrole) for an example policy. + + 1. {{< step_rancher-template >}} + 1. Click **Create**. + 1. **Optional:** Add additional node pools. +1. Review your cluster settings to confirm they are correct. Then click **Create**. + +{{< result_create-cluster >}} + +### Example Node IAM Policy + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*", + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` + +### Example Node IAM Policy with PassRole + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "iam:PassRole", + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*", + "arn:aws:iam::AWS_ACCOUNT_ID:role/your-role-name" + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionfinal.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionfinal.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionfinal.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionfinal.png diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionrole.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionrole.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionrole.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionrole.png diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionuser.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionuser.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/globalpermissionuser.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/globalpermissionuser.png diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancherroles1.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancherroles1.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancherroles1.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancherroles1.png diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancherroles2.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancherroles2.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancherroles2.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancherroles2.png diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancheruser.png b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancheruser.png similarity index 100% rename from content/rancher/v2.x/en/clusters/rke-clusters/node-pools/vsphere/rancheruser.png rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/rancheruser.png diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md new file mode 100644 index 00000000000..66530d8b917 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md @@ -0,0 +1,46 @@ +--- +title: Cluster Options +weight: 2250 +--- + +As you configure a new cluster that's provisioned using [RKE]({{< baseurl >}}/rke/v0.1.x/en/), you can choose custom Kubernetes options. + +You can configure Kubernetes options one of two ways: + +- [Rancher UI](#rancher-ui): Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster. +- [Config File](#config-file): Alternatively, you can create a [RKE config file]({{< baseurl >}}/rke/v0.1.x/en/config-options/) to customize any option offered by Kubernetes. + +## Rancher UI + +When creating a cluster using one of the options described in [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), you can configure basic Kubernetes options using the **Cluster Options** section. + +From this section you can choose: + +- The version of Kubernetes installed on your cluster nodes. Rancher uses its own version of Kubernetes based on [hyperkube](https://hub.docker.com/r/kubernetesonarm/hyperkube/), but packaged with more utilities. + +- Whether Rancher should check if the nodes are running a supported or unsupported version of Docker. If you only allow supported versions, the cluster automatically fails to launch if you have an unsupported version of Docker. Each Kubernetes version is tied to specific Docker versions based on what Kubernetes tests against. + +- The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. Out of the box, Rancher supports: + + - **[Canal](https://github.com/projectcalico/canal)**: In v2.0.0 - v2.0.4 and v2.0.6, this was the default option for these clusters was Canal with network isolation. With the network isolation automatically enabled, it prevented any pod communication between [projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/). + + - **[Flannel](https://github.com/coreos/flannel#flannel)**: In v2.0.5, this was the default option, which did not prevent any network isolation between projects. + + - **[Calico](https://docs.projectcalico.org/v3.1/introduction/)** + + > **Note:** Please carefully select which network provider you want to use as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, you would need to tear down the entire cluster and all applications to be able to switch to a different one. + +- Whether or not to use a [cloud provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider. + + > **Note:** If your cloud provider is not listed as an option, you will need to use the [config file option](#config-file) to use that cloud provider. Please reference the [RKE's cloud provider documentation]({{< baseurl >}}/rke/v0.1.x/en/config-options/cloud-providers/) on how to configure these other cloud providers. + +- Whether or not to use a [pod security policy]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies). You must have an existing pod security policy configured before you can use this option. + +## Config File + +Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{< baseurl >}}/rke/v0.1.x/en/config-options/) in an RKE installation. + +- To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**. +- To read from an existing RKE file, click **Read from File**. + +For an example of RKE config file syntax, see the [RKE documentation]({{< baseurl >}}/rke/v0.1.x/en/example-yamls/). diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/options/cloud-providers/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md similarity index 92% rename from content/rancher/v2.x/en/clusters/rke-clusters/options/cloud-providers/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md index f3c49a530a0..78f58542bc9 100644 --- a/content/rancher/v2.x/en/clusters/rke-clusters/options/cloud-providers/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md @@ -27,7 +27,7 @@ When using the `Amazon` cloud provider, you can leverage the following capabilit - Create/configure an IAM role - Configuring the ClusterID -> **Note:** When you create an [Amazon EC2 Cluster]({{< baseurl >}}/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), the `ClusterID` is automatically configured. +> **Note:** When you create an [Amazon EC2 Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), the `ClusterID` is automatically configured. #### Create/Configure an IAM Role @@ -35,8 +35,8 @@ All nodes added to the cluster must be able to interact with EC2 so that they ca [EC2 documentation: Creating an IAM Role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#create-iam-role) -- While creating an [Amazon EC2 cluster]({{< baseurl >}}/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), you must insert the name of the IAM role when creating the **Node Template**. -- While creating a [Custom cluster]({{< baseurl >}}/rancher/v2.x/en/clusters/custom-clusters/), you must manually attach the IAM role to the instance(s). +- While creating an [Amazon EC2 cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/#create-the-amazon-ec2-cluster), you must insert the name of the IAM role when creating the **Node Template**. +- While creating a [Custom cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/), you must manually attach the IAM role to the instance(s). The following IAM role can be created: @@ -164,7 +164,3 @@ Only hosts expected to be Load Balancer backends need to be in this group. ### External Links - [Cloud Providers](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/) - -### Tutorials - -- [Creating a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/) diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/_index.md new file mode 100644 index 00000000000..f4567141247 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/pod-security-policies/_index.md @@ -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, you can configure it to apply a PSP immediately. As you create the cluster, use the **Cluster Options** to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster. + +>**Prerequisite:** +>Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). +>**Note:** +>For security purposes, we recommend assigning a PSP as you create your clusters. + +To enable a default Pod Security Policy, set the **Pod Security Policy Support** option to **Enabled**, and then make a selection from the **Default Pod Security Policy** drop-down. + +When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster. diff --git a/content/rancher/v2.x/en/clusters/_index.md b/content/rancher/v2.x/en/clusters/_index.md deleted file mode 100644 index 9cab01a0590..00000000000 --- a/content/rancher/v2.x/en/clusters/_index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Creating Kubernetes Clusters -weight: 2000 -aliases: - - /rancher/v2.x/en/concepts/clusters/ - - /rancher/v2.x/en/concepts/clusters/cluster-providers/ - - /rancher/v2.x/en/tasks/clusters/ - - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/ ---- - -## What's a Kubernetes Cluster? - -A cluster is a group of computing resources that work as a team to accomplish a goal. Each individual computer in a cluster is called a _node_. - -## Cluster Creation - -Rancher simplifies creation of Kubernetes clusters by allowing you to create them with the Rancher UI rather than a config file. - -### Node Components - -A Kubernetes cluster contains 3 types of nodes: etcd nodes, control plane nodes, and worker nodes. - -#### etcd Nodes - -The etcd nodes are used to run the etcd database. etcd is a key value store used as Kubernetes’ backing store for all cluster data. Even though you can run etcd on a single node, you need 3, 5, or 7 nodes for redundancy. - -#### Control Plane Nodes - -The control plane nodes are used to run the Kubernetes API server, scheduler, and controller manager. Control plane nodes are stateless since all cluster data are stored on etcd nodes. You can run control plane on 1 node, although 2 or more nodes are required for redundancy. You can also run control plane on etcd nodes. - -#### Worker Nodes - -Worker nodes are used to run the kubelet and the workload. It also runs the storage and networking drivers and ingress controllers when required. You create as many worker nodes as needed for your workload needs. - - -Using Rancher, you can create Kubernetes clusters using a variety of options. Use the option that best fits your use case. - -## Hosted Kubernetes Providers - -By integrating with cloud APIs, Rancher lets you create new Kubernetes clusters through hosted providers, all within the Rancher UI. You can create clusters using either: - -- A hosted Kubernetes provider, such as Google GKE, Amazon EKS, or Microsoft AKS. -- An IaaS provider, using nodes provided from Amazon EC2, Microsoft Azure, or DigitalOcean. - -## Rancher-Launched Kubernetes - -Alternatively, you can use Rancher to create a cluster from your own existing nodes, using RKE. RKE is Rancher’s own lightweight Kubernetes installer. It works with any bare metal server, cloud provider, or virtualization platform. It integrates with node drivers to automatically provision nodes on AWS, Azure, DigitalOcean, vSphere, OpenStack, etc. Users can add custom nodes to the cluster by running the Rancher agent on these nodes. - -## Kubernetes Importation - -Finally, you also have the option of importing an existing Kubernetes cluster that you're already using into Rancher. - - -Using Rancher, you can create Kubernetes clusters using a variety of options. Use the option that best fits your use case. - -## Hosted Kubernetes Providers - -If you already have a cluster hosted by a Kubernetes provider such as Google GKE, Rancher can integrate with its cloud APIs, allowing you to manage your hosted cluster from the Rancher UI. - -## Infrastructure Providers - -Using Rancher, you can leverage APIs from major IaaS providers to create nodes and provision a new Kubernetes cluster. - -## From Existing Nodes - -Use Rancher to create a Kubernetes cluster on your on-premise bare metal servers. This option creates a cluster using RKE, which is Rancher's own lightweight Kubernetes installer. - -In addition to bare metal servers, RKE can also create clusters on less popular IaaS providers by integrating with node drivers. - -## Import Existing Clusters - -Users can import an existing Kubernetes cluster into Rancher. Rancher does not automate the provisioning, scaling, and upgrade of imported Kubernetes clusters. All other cluster management, policy management, and workload management capabilities of Rancher apply to imported clusters. diff --git a/content/rancher/v2.x/en/clusters/custom-clusters/_index.md b/content/rancher/v2.x/en/clusters/custom-clusters/_index.md deleted file mode 100644 index 1da681335d1..00000000000 --- a/content/rancher/v2.x/en/clusters/custom-clusters/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Creating a Custom Cluster -shortTitle: Custom Cluster -weight: 2400 - ---- diff --git a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/_index.md b/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/_index.md deleted file mode 100644 index e87e7e9561c..00000000000 --- a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Hosted Kubernetes Providers -weight: 2100 ---- - -If you already have a cluster hosted by a Kubernetes provider, Rancher can integrate with its cloud APIs, allowing you to manage your hosted cluster from the Rancher UI. - -Rancher supports the following Kubernetes providers: - - - -- [Google GKE (Google Container Engine)](#google-gke-google-container-engine) -- [Amazon EKS (Elastic Container Service)](#amazon-eks-elastic-container-service) -- [Microsoft AKS (Azure Container Service)](#microsoft-aks-azure-container-service) - - - -When setting up management of your hosted Kubernetes cluster in the Rancher UI, you are prompted for parameters required in all cluster creation scenarios: cluster name, user membership, how many nodes to create, and so on. However, each provider also requires information unique to the vendor. See more information about the information required for each provider below. - -## Google GKE (Google Container Engine) - -Before Rancher can manage a Google GKE cluster, you must create a service account with Google. This account also requires you to assign it the appropriate roles. - -Create a service account using [Google Cloud Platform](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts). GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication. - -The service account requires the following roles: - -- `project/viewer` -- `kubernetes-engine/admin` -- `service-account/user` - -For full instructions on how to complete these actions, see [Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances). - -After you create a service account, enter your service account private key into Rancher. - -## Amazon EKS (Elastic Container Service) - -Before Rancher can manage an Amazon EKS cluster, you must provide it with an Amazon access key that has the appropriate permissions assigned to it. - -Log into the [Amazon AWS Management Console](https://aws.amazon.com/console/) to assign yourself the appropriate IAM permissions and create an access key. Complete the actions below. - -- Assign the account you're using the IAM permissions to create clusters, modify clusters, and use the required API actions. For more information, see the official [EKS documentation](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html). - -- Create an Amazon access key and secret key. For more information, see [Managing Access Keys for IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) - -After you complete the two actions above, enter your access key and secret key in Rancher. - -## Microsoft AKS (Azure Container Service) - -Before Rancher can manage a Microsoft AKS cluster, you must provide it with information from your Azure Active Directory Service Principal (here after, _service principal_). Rancher uses this service principal to interact with the Azure API. - -For instruction on how to create a service principal, see [Service Principals with Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal). - -After you complete the action above, enter the information from your service principal in Rancher. diff --git a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/aks/_index.md b/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/aks/_index.md deleted file mode 100644 index 46227bd4862..00000000000 --- a/content/rancher/v2.x/en/clusters/hosted-kubernetes-clusters/aks/_index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Creating an AKS Cluster -shortTitle: Azure Container Service -weight: 2115 -aliases: - - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service/_index.md ---- - -You can use Rancher to create a cluster using Microsoft Azure Container Service. - - - -1. From the **Clusters** page, click **Add Cluster**. - -2. Choose **Azure Container Service**. - -3. Enter a **Cluster Name**. - -4. {{< step_create-cluster_member-roles >}} - -5. {{< step_create-cluster_cluster-options >}} - -6. Complete the **Account Access** form. This information is used to authenticate with Azure. - - - You can find your **Subscription ID** and **Tenant ID** on the [Microsoft Azure Portal](https://portal.azure.com/). - - To obtain a **Client ID** and **Client Secret**, follow the instructions in [this document](https://www.packer.io/docs/builders/azure-setup.html). -
-7. Use **Nodes** to provision each node in your cluster and choose a geographical region. - - [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) -
-8. Click **Create**. -
-9. Review your options to confirm they're correct. Then click **Create**. - -{{< result_create-cluster >}} diff --git a/content/rancher/v2.x/en/clusters/members/_index.md b/content/rancher/v2.x/en/clusters/members/_index.md deleted file mode 100644 index 9f51ec378a2..00000000000 --- a/content/rancher/v2.x/en/clusters/members/_index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Adding Users to Clusters -weight: 2500 -aliases: - - /rancher/v2.x/en/tasks/clusters/adding-managing-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]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-project-members/) instead. - -There are two contexts where you can add cluster members: - -- [Adding Members to a New Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster) - - You can add members to a cluster as you create it (recommended if possible). - -- [Adding Members to an Existing Cluster](#adding-members-to-an-existing-cluster) - - You can always add members to a cluster later. See below. - -### Adding Members to an Existing Cluster - -Following cluster creation, you can add users as cluster members so that they can access its resources. - -1. From the **Global** view, open the cluster that you want to add members to. - -2. From the main menu, select **Members**. Then click **Add Member**. - -3. Search for the user or group that you want to add to the cluster. - - If external authentication is configured: - - - Rancher returns users from your [external authentication]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/authentication/) source as you type. - - >**Using AD but can't find your users?** - >There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/authentication/active-directory/). - - - A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of. - - >**Note:** If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/authentication/#external-authentication-configuration-and-principal-users). - -4. Assign the user or group **Cluster** roles. - - [What are Cluster Roles?]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/#cluster-roles) - - >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. - > - > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/roles/#adding-a-custom-role). - > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/roles/#locking-unlocking-roles). - -**Result:** The chosen users are added to the cluster. - -- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user. -- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles. diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/_index.md b/content/rancher/v2.x/en/clusters/rke-clusters/_index.md deleted file mode 100644 index 71b52cdb6cc..00000000000 --- a/content/rancher/v2.x/en/clusters/rke-clusters/_index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Rancher Launched Kubernetes -weight: 2200 ---- - -## Infrastructure Providers - -Using Rancher, you can leverage APIs from major IaaS providers to create nodes and provision a new Kubernetes cluster, all from the Rancher UI. There's no need to log directly into your infrastructure providers's portal. - -You can create provider-hosted nodes from the Rancher UI by creating a node template. After providing Rancher with an access token from the vendor you're using, Rancher prompts you for specifications that it will send to your provider by API. The provider than provisions your nodes based on the template. - -Out-of-the-box, Rancher supports the following infrastructure providers: - -- Amazon EC2 -- Microsoft Azure -- DigitalOcean -- VMWare Vsphere - -Each vendor requires specific information that's used to authenticate with the provider API. Read more below to learn about the information required for each provider. - -## From Existing Nodes - -Use Rancher to create a Kubernetes cluster on your on-premise bare metal servers. This option creates a cluster using RKE, which is Rancher's own lightweight Kubernetes installer. In addition to bare metal servers, RKE can also create clusters on _any_ IaaS providers by integrating with node drivers. - -To use this option you'll need access to servers you intend to use as your Kubernetes cluster. Provision each server according to Rancher requirements, which includes some hardware specifications and Docker. After you install Docker on each server, run the command provided in the Rancher UI to turn each server into a Kubernetes node. diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/_index.md b/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/_index.md deleted file mode 100644 index 76b44c580a5..00000000000 --- a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Nodes hosted in an Infrastructure Provider -weight: 2205 -aliases: - - /rancher/v2.x/en/concepts/global-configuration/node-drivers/ - - /rancher/v2.x/en/tasks/global-configuration/node-drivers/ - - /rancher/v2.x/en/concepts/global-configuration/node-templates/ ---- - -### Node Drivers - - -Out-of-the-box, Rancher provides support for creating clusters using many popular cloud providers: Amazon EC2, Azure, DigitalOcean, and so on. However, you may want to create a cluster using another cloud provider. In these scenarios, you can create a custom node driver for the cloud provider and point Rancher toward it. - -For more information on creating node drivers, see [https://github.com/rancher/ui-driver-skel](https://github.com/rancher/ui-driver-skel). - -#### Managing Node Drivers - ->**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions: -> ->- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/#global-permissions) ->- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/#custom-global-permissions) with the [Manage Node Drivers]({{< baseurl >}}/rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/#global-permissions-reference) role assigned. - -## Adding Custom Node Drivers - -If you create a cluster using a cloud provider that {{< product >}} doesn't support out-of-the-box, you may need to add the provider's drivers (or create them yourself) so that your nodes function properly. - -1. From the **Global** view, select **Node Drivers** from the main menu. - -2. Click **Add Node Driver**. - -3. Complete the **Add Node Driver** form. Then click **Create**. - -## Activating Node Drivers - -Using the **Custom** option, you can create a cluster using virtually any cloud provider. However, by default, {{< product >}} only activates drivers for the most popular cloud providers. If you want to use another provider, you'll have to activate their drivers. - -1. From the **Global** view, select **Node Drivers** from the main menu. - -2. Select the inactive drivers that you want to use. Then click **Add Node Driver**. - - -### Node templates - -You can create new clusters within Rancher using _node templates_. A node template is a virtual machine image used to create a Kubernetes cluster. While creating a cluster, Rancher will prompt you for an image to use as a template. Follow the directions on screen to create the template. During cluster creation, Rancher clones the template and installs different Kubernetes components. - -After you add a node template to Rancher, its stored by the system so that you can use it when creating another cluster later. Node templates are bound to your login. After you add a template, you can remove them from your user profile. diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/_index.md b/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/_index.md deleted file mode 100644 index 54bba1dbad9..00000000000 --- a/content/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/_index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Creating an Amazon EC2 Cluster -shortTitle: Amazon EC2 -weight: 2210 -aliases: - - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2/ ---- -Use {{< product >}} to create a Kubernetes cluster in Amazon EC2. - -1. From the **Clusters** page, click **Add Cluster**. -1. Choose **Amazon EC2**. -1. Enter a **Cluster Name**. -1. {{< step_create-cluster_member-roles >}} -1. {{< step_create-cluster_cluster-options >}} -1. {{< step_create-cluster_node-pools >}} - 1. Click **Add Node Template**. - Complete each of the following forms using information available from the [EC2 Management Console](https://aws.amazon.com/ec2). - - **Account Access** holds the region and API Key used to create the cluster. - [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) - - **Zone and Network** configures the availability zone and network settings for your cluster. - - **Security Groups** configures the security groups applied to your cluster. - - **Instance** provisions your VM instances. - 1. {{< step_rancher-template >}} - 1. Click **Create**. - 1. **Optional:** Add additional node pools. -1. Review your cluster settings to confirm they're correct. Then click **Create**. - -{{< result_create-cluster >}} diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/options/_index.md b/content/rancher/v2.x/en/clusters/rke-clusters/options/_index.md deleted file mode 100644 index 8dbef6dea51..00000000000 --- a/content/rancher/v2.x/en/clusters/rke-clusters/options/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Cluster Options -weight: 2250 ---- diff --git a/content/rancher/v2.x/en/clusters/rke-clusters/options/pod-security-policies/_index.md b/content/rancher/v2.x/en/clusters/rke-clusters/options/pod-security-policies/_index.md deleted file mode 100644 index 7919b19cce0..00000000000 --- a/content/rancher/v2.x/en/clusters/rke-clusters/options/pod-security-policies/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Pod Security Policies -weight: 2260 ---- diff --git a/content/rancher/v2.x/en/concepts/_index.md b/content/rancher/v2.x/en/concepts/_index.md deleted file mode 100644 index 1242f168e07..00000000000 --- a/content/rancher/v2.x/en/concepts/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- - title: Concepts - weight: 2000 ---- -This section describes the different features in Rancher, the ideas behind them, and how they work. - -Choose a concept from the side-menu to start learning about Rancher! diff --git a/content/rancher/v2.x/en/concepts/projects/_index.md b/content/rancher/v2.x/en/concepts/projects/_index.md deleted file mode 100644 index d4704f3bfb0..00000000000 --- a/content/rancher/v2.x/en/concepts/projects/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Projects -weight: 2150 ---- - -_Projects_ are a new concept introduced by Rancher. They are not a native Kubernetes construct. A project captures a set of policies for a set of namespaces. A user can be assigned a specific role in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/creating-roles/#adding-a-custom-role). Policies include Kubernetes Role-Based Access Control (RBAC) policies and pod security policies. Rancher 2.0 also implements a canned network policy that isolates containers in different projects. Future versions of Rancher will implement more flexible network policies. - -### Authorization - -Non-administrative users are only authorized for project access after an administrator explicitly adds them to the project's **Members** tab. - ->**Exception:** -> Non-administrative users can access projects that they create themselves. - -### Pod Security Policies - -Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level. - -## Namespaces - -Kubernetes resources belong to specific namespaces. Rancher 2.0 relies on namespaces to isolate resources among users and apps. When the user deploys an app from the catalog, for example, he can choose to deploy that app into its own namespace, so that resource names in one app will not conflict with resource names in another. Namespaces must be globally unique. It is often difficult for users to pick unique namespace names. Rancher therefore encourages the pattern where users work with projects, and the system generates unique namespace names automatically. - -For more information, see the [Kubernetes Namespaces Documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). - -## Related Links - -- [Project Tutorials]({{< baseurl >}}/rancher/v2.x/en/tasks/projects) diff --git a/content/rancher/v2.x/en/concepts/resources/_index.md b/content/rancher/v2.x/en/concepts/resources/_index.md deleted file mode 100644 index 70411d7e264..00000000000 --- a/content/rancher/v2.x/en/concepts/resources/_index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Resources -weight: 2275 ---- - -Within the context of a Rancher project or namespace, _resources_ are files and data that support operation of your pods. Within this scope, resources include: - -- [Certificates](#certificates) -- [ConfigMaps](#configmaps) -- [Secrets](#secrets) -- [Registries](#registries) - -Rancher extends the application of the Kubernetes namespace resources listed above to [projects]({{< baseurl >}}/rancher/v2.x/en/concepts/projects/), which are Rancher-specific constructs. In the hierarchy of Rancher objects, projects contain namespaces. Therefore, any resources available within a project are available for all namespaces within that project. - -Within Kubernetes, certificates, registries, and secrets are all considered [secrets](https://kubernetes.io/docs/concepts/configuration/secret/). Therefore, within a single project or namespace, these resources must have unique names to avoid conflicts. Although secrets are primarily used to carry sensitive information, they have other uses as well. Read on below. - -## Certificates - -When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by navigating to its project or namespace, and then uploading the certificate. You can then add the certificate to the ingress deployment. - -## ConfigMaps - -While most types of Kubernetes secrets store sensitive information, [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect). - -ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount. - ->**Note:** ConfigMaps are only available within namespaces and not projects. - -## Secrets - -[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets) store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs. -When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount. - ->**Note:** Any update to secrets won't reflect automatically inside pods, until the pods are restarted. - -## Registries - -Registries are secrets containing credentials used to authenticate with [private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). Deployments use these secrets to authenticate with a private registry and then pull a Docker image hosted on it. - ->**Note:** Currently, credentials are pulled automatically only if the workload is created in the Rancher UI and not kubectl. - -## Related Links - -- [Adding SSL Certificates]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-ssl-certificates) -- [Adding ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-configmaps) -- [Adding Secrets]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-a-secret) -- [Adding Registries]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-registries) diff --git a/content/rancher/v2.x/en/concepts/service-discovery/_index.md b/content/rancher/v2.x/en/concepts/service-discovery/_index.md deleted file mode 100644 index b3dff86b4b8..00000000000 --- a/content/rancher/v2.x/en/concepts/service-discovery/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Service Discovery -weight: 2200 -draft: true ---- - -## Related Links - -### Tutorials - -- [Adding a DNS Record]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/add-a-dns-record) - -### External Links - -- [Services](https://kubernetes.io/docs/concepts/services-networking/service/) -- [Adding entries to Pod /etc/hosts with HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) diff --git a/content/rancher/v2.x/en/concepts/volumes-and-storage/_index.md b/content/rancher/v2.x/en/concepts/volumes-and-storage/_index.md deleted file mode 100644 index a7cb44d3c05..00000000000 --- a/content/rancher/v2.x/en/concepts/volumes-and-storage/_index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Volumes and Storage -weight: 2225 ---- -There are two ways to create volumes on Kubernetes: Persistent Volumes (PVs) and Storage Classes. - -## Persistent Volumes - -_Persistent Volumes_ are pre-provisioned storage volumes that you can bind to specific pods later. For example, in Amazon EC2, you might want to create a number of Elastic Block Store (EBS) volumes before you start running your application. Each pre-provisioned EBS volume corresponds to a Kubernetes persistent volume. When the application starts, it creates Persistent Volume Claims (PVCs) that bind to persistent volumes. A PVC corresponds to a Docker volume. Each PVC binds to one PV that includes the minimum resources that the PVC requires. The following figure illustrates the relationship between pods, PVCs, PVs, and the underlying cloud storage. - -![Persistent Volumes]({{< baseurl >}}/img/rancher/persistent-volume.png) - -Rancher allows you to create PVs at cluster level and bind them to PVCs later. Volumes are managed on a per-project basis. - -## Storage Classes - -Storage Classes allow you to create PVCs dynamically without having to create PVs first. For example, an Amazon EBS Storage Class will dynamically create EBS volumes and bind them to PVCs. A Storage Class is similar to the notion of a _storage driver_. The following figure illustrates how a PVC creation triggers the dynamic provisioning of an underlying EBS volume. - -![Storage Classes]({{< baseurl >}}/img/rancher/storage-classes.png) - -### Storage and Cloud Providers - -Each storage class contains the fields `provisioner`, `parameters`, and `reclaimPolicy`, which are used when a persistent volume that belongs to the class needs to be dynamically provisioned. - -The `provisioner` determines which volume plugin is used to provision the persistent volumes. You can define storage classes for the following provisioners: - -- Amazon EBS Disk -- AzureFile -- AzureDisk -- Ceph RBD -- Gluster Volume -- Google Persistent Disk -- Longhorn -- Openstack Cinder Volume -- Portworx Volume -- Quobyte Volume -- ScaleIO Volume -- StorageOS -- Vmware vSphere Volume - -In addition to customizing each provisioner's options for the storage class, you can also define the volume `reclaimPolicy`. There are two options available: - -- Delete volumes and underlying device when released by workloads. -- Retain the volume for manual cleanup. - -Finally, you can define custom `MountOptions` for the persistent volume created. - -`parameters` are specific to each cloud storage provisioner. For full information about the storage classes provisioner parameters, refer to the official [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters). - -## Related Links - -### External Docs - -- [Storage](https://kubernetes.io/docs/concepts/storage/) - -### Tutorials - -- [Adding Storage]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage) -- [Adding Persistent Volume Claims]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim) diff --git a/content/rancher/v2.x/en/faq/_index.md b/content/rancher/v2.x/en/faq/_index.md index 457f7c1a8ae..534424ce53f 100644 --- a/content/rancher/v2.x/en/faq/_index.md +++ b/content/rancher/v2.x/en/faq/_index.md @@ -71,7 +71,7 @@ That is definitely the focus of the v1.6 stream. We're continuing to improve tha When creating an environment in Rancher v2.0, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm. -#### Is it possible to manage Azure Container Services with Rancher v2.0? +#### Is it possible to manage Azure Kubernetes Services with Rancher v2.0? Yes. #### What about Windows support? diff --git a/content/rancher/v2.x/en/faq/technical/_index.md b/content/rancher/v2.x/en/faq/technical/_index.md index 3df6cd1abfc..ad6ece2eb43 100644 --- a/content/rancher/v2.x/en/faq/technical/_index.md +++ b/content/rancher/v2.x/en/faq/technical/_index.md @@ -1,6 +1,6 @@ --- - title: Technical - weight: 8005 +title: Technical +weight: 8005 --- ### How can I reset the admin password? @@ -64,7 +64,7 @@ Node Templates can be accessed by opening your account menu (top right) and sele ### Why is my Layer-4 Load Balancer in `Pending` state? -The Layer-4 Load Balancer is created as `type: LoadBalancer`. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in `Pending` state forever. More information can be found on [Cloud Providers]({{< baseurl >}}/rancher/v2.x/en/concepts/clusters/cloud-providers/) or [Create External Load Balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) +The Layer-4 Load Balancer is created as `type: LoadBalancer`. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in `Pending` state forever. More information can be found on [Cloud Providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) or [Create External Load Balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) ### Where is the state of Rancher stored? diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index b895c5aa800..9f09b076be9 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -165,7 +165,7 @@ Run the following commands from your Linux host. You have a couple of options: - Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). -- Create a Kubernetes cluster: [Creating a Cluster]({{ }}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/). +- Create a Kubernetes cluster: [Creating a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/).
diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/_index.md new file mode 100644 index 00000000000..7c86eae8388 --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/_index.md @@ -0,0 +1,21 @@ +--- +title: Kubernetes in Rancher +weight: 3000 +aliases: + - /rancher/v2.x/en/concepts/ + - /rancher/v2.x/en/tasks/ + - /rancher/v2.x/en/concepts/resources/ +--- + + + +Within the context of a Rancher project or namespace, _resources_ are files and data that support operation of your pods. Within this scope, resources include: + +- [Certificates]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/certificates/) +- [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/configmaps/) +- [Secrets]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/secrets/) +- [Registries]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/registries/) + +Rancher extends the application of the Kubernetes namespace resources listed above to [projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/), which are Rancher-specific constructs. In the hierarchy of Rancher objects, projects contain namespaces. Therefore, any resources available within a project are available for all namespaces within that project. + +Within Kubernetes, certificates, registries, and secrets are all considered [secrets](https://kubernetes.io/docs/concepts/configuration/secret/). Therefore, within a single project or namespace, these resources must have unique names to avoid conflicts. Although secrets are primarily used to carry sensitive information, they have other uses as well. diff --git a/content/rancher/v2.x/en/tasks/projects/add-ssl-certificates/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/certificates/_index.md similarity index 82% rename from content/rancher/v2.x/en/tasks/projects/add-ssl-certificates/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/certificates/_index.md index a9dfeaac88d..1ec1dcb22f5 100644 --- a/content/rancher/v2.x/en/tasks/projects/add-ssl-certificates/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/certificates/_index.md @@ -1,8 +1,11 @@ --- -title: Adding SSL Certificates -weight: +title: SSL Certificates +weight: 3060 +aliases: + - /rancher/v2.x/en/tasks/projects/add-ssl-certificates/ --- -When you create an ingress within Rancher/Kubernetes, you must provide it with a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by navigating to its project or namespace, and then uploading the certificate. + +When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by navigating to its project or namespace, and then uploading the certificate. You can then add the certificate to the ingress deployment. Add SSL certificates to either projects, namespaces, or both. A project scoped certificate will be available in all its namespaces. @@ -38,4 +41,4 @@ Add SSL certificates to either projects, namespaces, or both. A project scoped c ## What's Next? -Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see [Adding Ingress]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/add-ingress/). +Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see [Adding Ingress]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/ingress/). diff --git a/content/rancher/v2.x/en/tasks/projects/add-configmaps/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/configmaps/_index.md similarity index 68% rename from content/rancher/v2.x/en/tasks/projects/add-configmaps/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/configmaps/_index.md index 87476fd20c7..ae28e221bac 100644 --- a/content/rancher/v2.x/en/tasks/projects/add-configmaps/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/configmaps/_index.md @@ -1,8 +1,17 @@ --- -title: Adding ConfigMaps -weight: +title: ConfigMaps +weight: 3061 +aliases: + - /rancher/v2.x/en/tasks/projects/add-configmaps --- + +While most types of Kubernetes secrets store sensitive information, [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect). + +ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount. + +>**Note:** ConfigMaps are only available within namespaces and not projects. + ConfigMaps store general configuration information for an application, such as configuration files, command-line arguments, environment variables, etc. ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. Add ConfigMaps to your Rancher workspaces so that you can add them to your workloads later. For more information on ConfigMaps, see the official [Kubernetes Documentation: Using ConfigMap](https://kubernetes-v1-4.github.io/docs/user-guide/configmap/). >**Note:** ConfigMaps can only be applied to namespaces and not projects. @@ -21,7 +30,7 @@ ConfigMaps store general configuration information for an application, such as c 1. Click **Save**. - >**Note:** Don't use ConfigMaps to store sensitive data [use a secret](../add-a-secret). + >**Note:** Don't use ConfigMaps to store sensitive data [use a secret]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/secrets/). > >**Tip:** You can add multiple key value pairs to the ConfigMap by copying and pasting. > @@ -36,4 +45,4 @@ Now that you have a ConfigMap added to a namespace, you can add it to a workload - Application environment variables. - Specifying parameters for a Volume mounted to the workload. -For more information on adding ConfigMaps to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/deploy-workloads/). \ No newline at end of file +For more information on adding ConfigMaps to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/). diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/_index.md new file mode 100644 index 00000000000..555cf2c180d --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/_index.md @@ -0,0 +1,72 @@ +--- +title: Editing Clusters +weight: 3015 +--- + +## Editing the Cluster Membership + +Following cluster creation, you can add users as cluster members so that they can access its resources. + +1. From the **Global** view, open the cluster that you want to add members to. + +2. From the main menu, select **Members**. Then click **Add Member**. + +3. Search for the user or group that you want to add to the cluster. + + If external authentication is configured: + + - Rancher returns users from your [external authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) source as you type. + + >**Using AD but can't find your users?** + >There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/). + + - A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of. + + >**Note:** If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). + +4. Assign the user or group **Cluster** roles. + + [What are Cluster Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) + + >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. + > + > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). + > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles). + +**Result:** The chosen users are added to the cluster. + +- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user. +- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles. + +## Cluster Options + +>**Note:** These cluster options are only available for [clusters that Rancher has launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). + +### Adding/Changing a Pod Security Policy + +If you don't apply a PSP as you create your cluster, you can always add one later. + +>**Prerequisite:** +>Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). + +1. From the **Global** view, find the cluster that you want to apply your PSP to. Select **Vertical Ellipsis (...) > Edit** for the cluster you want to enable PSPs for. + +2. Expand the **Cluster Options** accordion. + +3. From **Pod Security Policy Support**, select **Enabled**. + + >**Note:** Not all cluster providers support PSPs, so this option may not be available. + + **Step Result:** The **Default Pod Security Policy** drop-down activates. + +4. From **Default Pod Security Policy**, select the PSP you want to apply to the cluster. + +5. Click **Save**. + +**Result:** The PSP is applied to the cluster and any projects within the cluster. + +>**Note:** 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. + +### Node pools + +Changing the nodes in a RKE cluster diff --git a/content/rancher/v2.x/en/concepts/clusters/kubeconfig-files/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/kubeconfig/_index.md similarity index 87% rename from content/rancher/v2.x/en/concepts/clusters/kubeconfig-files/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/kubeconfig/_index.md index c13ebb3e2e6..d66f8f8b174 100644 --- a/content/rancher/v2.x/en/concepts/clusters/kubeconfig-files/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/kubeconfig/_index.md @@ -1,6 +1,8 @@ --- title: Kubeconfig Files -weight: 2100 +weight: 3010 +aliases: + - /rancher/v2.x/en/concepts/clusters/kubeconfig-files/ --- A _kubeconfig file_ is a file used to configure access to Kubernetes when used in conjunction with the kubectl commandline tool (or other clients). @@ -11,11 +13,9 @@ When you create a cluster using the Rancher GUI, Rancher automatically creates a This kubeconfig file and its contents are specific to the cluster you are viewing. You will need a separate kubeconfig file for each cluster that you have access to in Rancher. -For more information, see [Using kubectl to Access a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster). +For more information, see [Using kubectl to Access a Cluster]({{< baseurl >}}/rancher/v2.x/en//kubernetes-in-rancher/kubectl). >**Note:** By default, kubectl checks `~/.kube/config` for kubeconfig files, but you can use any directory you want using the `--kubeconfig` flag. For example: >``` kubectl --kubeconfig /custom/path/kube.config get pods ``` - - diff --git a/content/rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/kubectl/_index.md similarity index 86% rename from content/rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/kubectl/_index.md index cb9930f726e..63377479f00 100644 --- a/content/rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/kubectl/_index.md @@ -1,18 +1,20 @@ --- title: Using kubectl to Access a Cluster -weight: 3450 +weight: 3005 +aliases: + - /rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster/ --- You can access and manage your Kubernetes clusters using kubectl in two ways: - [Accessing Clusters with kubectl Shell](#accessing-clusters-with-kubectl-shell) -- [Accessing Clusters with kubectl CLI and a kubeconfig File](#accessing-clusters-with-kubectl-cli-and-a-kubeconfig-file) +- [Accessing Clusters with kubectl CLI and a kubeconfig File]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/kubeconfig/) ## Accessing Clusters with kubectl Shell You can access and manage your clusters by logging into Rancher and opening the kubectl shell. 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. For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/). @@ -26,7 +28,7 @@ Alternatively, you can access your clusters by installing kubectl on your workst 2. Log into Rancher. From the **Global** view, open the cluster that you want to access with kubectl. -3. Copy the cluster's kubeconfig file to your workstation. +3. Copy the cluster's kubeconfig file to your workstation. 1. Click **Kubeconfig File**. @@ -41,4 +43,4 @@ Alternatively, you can access your clusters by installing kubectl on your workst ``` 4. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster. - For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/). \ No newline at end of file + For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/). diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/_index.md new file mode 100644 index 00000000000..bfc50aec574 --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/_index.md @@ -0,0 +1,4 @@ +--- +title: Load Balancing and Ingresses +weight: 3040 +--- diff --git a/content/rancher/v2.x/en/tasks/workloads/add-ingress/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/ingress/_index.md similarity index 95% rename from content/rancher/v2.x/en/tasks/workloads/add-ingress/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/ingress/_index.md index a527ae01887..6f288d6bf5b 100644 --- a/content/rancher/v2.x/en/tasks/workloads/add-ingress/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/ingress/_index.md @@ -1,6 +1,8 @@ --- -title: Adding Ingress -weight: 50 +title: Ingress +weight: 3042 +aliases: + - /rancher/v2.x/en/tasks/workloads/add-ingress/ --- Ingress can be added for workloads to provide load balancing, SSL termination and host/path based routing. @@ -16,13 +18,13 @@ Ingress can be added for workloads to provide load balancing, SSL termination an 1. Create ingress forwarding **Rules**. - **Automatically generate a xip.io hostname** - + If you choose this option, ingress routes requests to hostname to a DNS name that's automatically generated. Rancher uses [xip.io](http://xip.io/) to automatically generates the DNS name. This option is best used for testing, _not_ production environments. >**Note:** To use this option, you must be able to resolve to `xip.io` addresses. - + 1. Add a **Target Backend**. By default, a workload is added to the ingress, but you can add more targets by clicking either **Service** or **Workload**. - + 1. **Optional:** If you want specify a workload or service when a request is sent to a particular hostname path, add a **Path** for the target. For example, if you want requests for `www.mysite.com/contact-us` to be sent to a different service than `www.mysite.com`, enter `/contact-us` in the **Path** field. Typically, the first rule that you create does not include a path. @@ -32,13 +34,13 @@ Ingress can be added for workloads to provide load balancing, SSL termination an 1. Enter the **Port** number that each target operates on. - **Specify a hostname to use** - + If you use this option, ingress routes requests for a hostname to the service or workload that you specify. 1. Enter the hostname that your ingress will handle request forwarding for. For example, `www.mysite.com`. - + 1. Add a **Target Backend**. By default, a workload is added to the ingress, but you can add more targets by clicking either **Service** or **Workload**. - + 1. **Optional:** If you want specify a workload or service when a request is sent to a particular hostname path, add a **Path** for the target. For example, if you want requests for `www.mysite.com/contact-us` to be sent to a different service than `www.mysite.com`, enter `/contact-us` in the **Path** field. Typically, the first rule that you create does not include a path. @@ -46,23 +48,23 @@ Ingress can be added for workloads to provide load balancing, SSL termination an 1. Select a workload or service from the **Target** drop-down list for each target you've added. 1. Enter the **Port** number that each target operates on. - + - **Use as the default backend** - + Use this option to set an ingress rule for handling requests that don't match any other ingress rules. For example, use this option to route requests that can't be found to a `404` page. >**Note:** If you deployed Rancher using RKE, a default backend for 404s and 202s is already configured. - + 1. Add a **Target Backend**. Click either **Service** or **Workload** to add the target. - + 1. Select a service or workload from the **Target** drop-down list. 1. **Optional:** click **Add Rule** to create additional ingress rules. For example, after you create ingress rules to direct requests for your hostname, you'll likely want to create a default backend to handle 404s. 1. If any of your ingress rules handle requests for encrypted ports, add a certificate to encrpyt/decrypt communications. - >**Note:** You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see [Adding SSL Certificates](../../projects/add-ssl-certificates/). + >**Note:** You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see [Adding SSL Certificates]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/certificates/). 1. Click **Add Certificate**. diff --git a/content/rancher/v2.x/en/concepts/load-balancing/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/load-balancers/_index.md similarity index 97% rename from content/rancher/v2.x/en/concepts/load-balancing/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/load-balancers/_index.md index f78cdbb88b0..f75aa11170f 100644 --- a/content/rancher/v2.x/en/concepts/load-balancing/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/load-balancers-and-ingress/load-balancers/_index.md @@ -1,6 +1,8 @@ --- -title: Load Balancing -weight: 2175 +title: Load Balancers +weight: 3041 +aliases: + - /rancher/v2.x/en/concepts/load-balancing/ --- Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing. @@ -68,4 +70,3 @@ The benefit of using xip.io is that you obtain a working entrypoint URL immediat ### Ingress Controller - [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress) - diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/_index.md new file mode 100644 index 00000000000..316621fed6e --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/_index.md @@ -0,0 +1,79 @@ +--- +title: Projects and Namespaces +weight: 3020 +aliases: + - /rancher/v2.x/en/concepts/projects/ + - /rancher/v2.x/en/tasks/projects/ + - /rancher/v2.x/en/tasks/projects/create-project/ +--- + +_Projects_ are a new concept introduced by Rancher. They are not a native Kubernetes construct. A project captures a set of policies for a set of namespaces. A user can be assigned a specific role in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). Policies include Kubernetes Role-Based Access Control (RBAC) policies and pod security policies. Rancher 2.0 also implements a canned network policy that isolates containers in different projects. Future versions of Rancher will implement more flexible network policies. + +## Authorization + +Non-administrative users are only authorized for project access after an administrator explicitly adds them to the project's **Members** tab. + +>**Exception:** +> Non-administrative users can access projects that they create themselves. + +## Pod Security Policies + +Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level. + +## Namespaces + +Kubernetes resources belong to specific namespaces. Rancher 2.0 relies on namespaces to isolate resources among users and apps. When the user deploys an app from the catalog, for example, he can choose to deploy that app into its own namespace, so that resource names in one app will not conflict with resource names in another. Namespaces must be globally unique. It is often difficult for users to pick unique namespace names. Rancher therefore encourages the pattern where users work with projects, and the system generates unique namespace names automatically. + +For more information, see the [Kubernetes Namespaces Documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). + +## Creating Projects + +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**. + +1. **Optional:** Select a **Pod Security Policy**. 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. + + >**Note:** This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). + +1. **Recommended:** Add project members. + + Use the **Members** accordion to provide other users with project access and roles. + + By default, your user is added as the project `Owner`. + + 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. + + [What are Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) + + >**Tip:** Choose Custom to create a custom role on the fly: [Custom Project Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles). + + 1. To add more members, repeat substeps a—c. + + +1. Click **Create**. + +**Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view. + +## Switching Projects + +To switch between clusters, use the **Global** drop-down available in the main menu. + +![Global Menu]({{< baseurl >}}/img/rancher/global-menu.png) + +Alternatively, you can switch between projects and clusters using the main menu. + +- To switch between clusters, open the **Global** view and select **Clusters** from the main menu. Then open a cluster. +- To switch between projects, open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open. diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/editing-projects/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/editing-projects/_index.md new file mode 100644 index 00000000000..79b6ef59fb8 --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/editing-projects/_index.md @@ -0,0 +1,75 @@ +--- +title: Editing Projects +weight: 3021 +aliases: + - /rancher/v2.x/en/tasks/projects/create-project/ +--- + +After projects are created, there are certain aspects that can be changed later. + +## Adding Members + +Following project creation, you can add users as project members so that they can access its resources. + +1. From the **Global** view, open the project that you want to add members to. + +2. From the main menu, select **Members**. Then click **Add Member**. + +3. Search for the user or group that you want to add to the project. + + If external authentication is configured: + + - Rancher returns users from your external authentication source as you type. + + - A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in. + + >**Note:** If you are logged in as a local user, external users do not display in your search results. + +1. Assign the user or group **Project** roles. + + [What are Project Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) + + >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. + > + > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles). + > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/). + +**Result:** The chosen users are added to the 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. + +## Editing the Pod Security Policy + +>**Note:** These cluster options are only available for [clusters that Rancher has launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). + +You can always assign a PSP to an existing project if you didn't assign one during creation. + +>**Prerequisites:** +> +> - Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). +> - Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [Existing Cluster: Adding a Pod Security Policy]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/editing-clusters/#adding-changing-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**. + +3. Find the project that you want to add a PSP to. From that project, select **Vertical Ellipsis (...) > Edit**. + +4. 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. + + >**Prerequisites:** + > + > - Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). + > - Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. + +5. 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 if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP. diff --git a/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/project-members/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/project-members/_index.md new file mode 100644 index 00000000000..3ce56f7e921 --- /dev/null +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/project-members/_index.md @@ -0,0 +1,20 @@ +--- +title: Adding Users to Projects +weight: 3022 +aliases: + - /rancher/v2.x/en/tasks/projects/add-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. + +>**Tip:** Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/cluster-members/) instead. + +There are two contexts where you can add project members: + +- [Adding Members when Creating New Projects]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/) + + You can add members to a project as you create it (recommended if possible). + +- [Adding Members to an Existing Project]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/projects-and-namespaces/editing-projects/) + + You can always add members to a project later. diff --git a/content/rancher/v2.x/en/tasks/projects/add-registries/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/registries/_index.md similarity index 73% rename from content/rancher/v2.x/en/tasks/projects/add-registries/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/registries/_index.md index ab5a9f56bde..e602689f2a7 100644 --- a/content/rancher/v2.x/en/tasks/projects/add-registries/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/registries/_index.md @@ -1,10 +1,16 @@ --- -title: Adding Registries -weight: +title: Registries +weight: 3063 +aliases: + - /rancher/v2.x/en/tasks/projects/add-registries/ --- Registries are secrets containing credentials used to authenticate with [private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). Deployments use these secrets to authenticate with a private registry and then pull a Docker image hosted on it. +>**Note:** Currently, credentials are pulled automatically only if the workload is created in the Rancher UI and not kubectl. + +Registries are secrets containing credentials used to authenticate with [private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). Deployments use these secrets to authenticate with a private registry and then pull a Docker image hosted on it. + >**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) configured. >**Note:** Currently, credentials are pulled automatically only if the workload is created in the Rancher UI and not kubectl. @@ -22,11 +28,11 @@ Registries are secrets containing credentials used to authenticate with [private 1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. 1. Click **Save**. - + **Result:** Your secret is added to the project or namespace, depending on the scope you chose. You can view the secret in the Rancher UI from the **Resources > Registries** view. ## What's Next? Now that you have a registry added to the project or namespace, you can add it to a workload that's deploying an image from your private registry. -For more information on adding a registry to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/deploy-workloads/). +For more information on adding a registry to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/). diff --git a/content/rancher/v2.x/en/tasks/projects/add-a-secret/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/secrets/_index.md similarity index 70% rename from content/rancher/v2.x/en/tasks/projects/add-a-secret/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/secrets/_index.md index c95c8ccb660..dd92fdec569 100644 --- a/content/rancher/v2.x/en/tasks/projects/add-a-secret/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/secrets/_index.md @@ -1,8 +1,15 @@ --- -title: Adding a Secret -weight: +title: Secrets +weight: 3062 +aliases: + - /rancher/v2.x/en/tasks/projects/add-a-secret --- +[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets) store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs. +When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount. + +>**Note:** Any update to secrets won't reflect automatically inside pods, until the pods are restarted. + [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets) store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs. When creating a secret, you can make it available for any deployment within a project, or you can limit it to a single namespace. @@ -24,11 +31,11 @@ When creating a secret, you can make it available for any deployment within a pr > ![Bulk Key Value Pair Copy/Paste]({{< baseurl >}}/img/rancher/bulk-key-values.gif) 1. Click **Save**. - + **Result:** Your secret is added to the project or namespace, depending on the scope you chose. You can view the secret in the Rancher UI from the **Resources > Secrets** view. ## What's Next? Now that you have a secret added to the project or namespace, you can add it to a workload that you deploy. -For more information on adding secret to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/deploy-workloads/). +For more information on adding secret to a workload, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/). diff --git a/content/rancher/v2.x/en/tasks/workloads/add-a-dns-record/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/service-discovery/_index.md similarity index 94% rename from content/rancher/v2.x/en/tasks/workloads/add-a-dns-record/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/service-discovery/_index.md index aaba2afdc6f..6bc3693feb0 100644 --- a/content/rancher/v2.x/en/tasks/workloads/add-a-dns-record/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/service-discovery/_index.md @@ -1,8 +1,11 @@ --- -title: Adding a DNS Record -weight: 75 +title: Service Discovery +weight: 3045 +aliases: + - /rancher/v2.x/en/tasks/workloads/add-a-dns-record/ --- + For every workload created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention: `..svc.cluster.local`. @@ -47,10 +50,6 @@ However, you also have the option of creating additional Service Discovery recor ## Related Links -### Tutorials - -- [Service Discovery]({{< baseurl >}}/rancher/v2.x/en/concepts/service-discovery) - ### External Links - [Adding entries to Pod /etc/hosts with HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-storage/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/_index.md similarity index 60% rename from content/rancher/v2.x/en/tasks/clusters/adding-storage/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/_index.md index f3c86dbaedf..ae2aa655b40 100644 --- a/content/rancher/v2.x/en/tasks/clusters/adding-storage/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/_index.md @@ -1,14 +1,26 @@ --- -title: Adding Storage -weight: 3500 +title: Volumes and Storage +weight: 3050 +aliases: + - /rancher/v2.x/en/concepts/volumes-and-storage/ + - /rancher/v2.x/en/tasks/clusters/adding-storage/ --- +There are two ways to create volumes on Kubernetes: Persistent Volumes (PVs) and Storage Classes. ->**Prerequisites:** +## Persistent Volumes + +_Persistent Volumes_ are pre-provisioned storage volumes that you can bind to specific pods later. For example, in Amazon EC2, you might want to create a number of Elastic Block Store (EBS) volumes before you start running your application. Each pre-provisioned EBS volume corresponds to a Kubernetes persistent volume. When the application starts, it creates Persistent Volume Claims (PVCs) that bind to persistent volumes. A PVC corresponds to a Docker volume. Each PVC binds to one PV that includes the minimum resources that the PVC requires. The following figure illustrates the relationship between pods, PVCs, PVs, and the underlying cloud storage. + +![Persistent Volumes]({{< baseurl >}}/img/rancher/persistent-volume.png) + +Rancher allows you to create PVs at cluster level and bind them to PVCs later. Volumes are managed on a per-project basis. + +### Adding a Persistent Volume + +>**Prerequisites:** > ->- Working with storage requires the `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#project-role-reference). ->- You must have a storage medium provisioned. For more information, see [Provisioning Storage](provisioning-storage). - -## Adding a Persistent Volume +>- Working with storage requires the `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference). +>- You must have a storage medium provisioned. For more information, see [Provisioning Storage]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/). Your containers can store data on themselves, but if a container fails, that data is lost. To solve this issue, Kubernetes offers _persistent volumes_, which are external storage disks or file systems that your containers can access. If a container crashes, its replacement container can access the data in a persistent volume without any data loss. @@ -30,7 +42,7 @@ Persistent volumes can either be a disk or file system that you host on premise, 1. Select the **Volume Plugin** for the disk type or service that you're using. >**Note:** If the cluster you are adding storage for is a cloud service that also offers cloud storage, you must enable the `cloud provider` option for the cluster, and you must use the service's plug-in to use cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it: - + 1. You must enable the `cloud provider` option for the EC2 cluster. 2. You must use the `Amazon EBS Disk` volume plugin. @@ -58,9 +70,44 @@ Persistent volumes can either be a disk or file system that you host on premise, **Result:** Your new persistent volume is created. -## Adding Storage Classes +## Storage Classes -_Storage Classes_ allow you to dynamically provision persistent volumes on demand. Think of storage classes as storage profiles that are created automatically upon a request (which is known as a _persistent volume claim_). +Storage Classes allow you to create PVCs dynamically without having to create PVs first. For example, an Amazon EBS Storage Class will dynamically create EBS volumes and bind them to PVCs. A Storage Class is similar to the notion of a _storage driver_. The following figure illustrates how a PVC creation triggers the dynamic provisioning of an underlying EBS volume. + +![Storage Classes]({{< baseurl >}}/img/rancher/storage-classes.png) + +### Storage and Cloud Providers + +Each storage class contains the fields `provisioner`, `parameters`, and `reclaimPolicy`, which are used when a persistent volume that belongs to the class needs to be dynamically provisioned. + +The `provisioner` determines which volume plugin is used to provision the persistent volumes. You can define storage classes for the following provisioners: + +- Amazon EBS Disk +- AzureFile +- AzureDisk +- Ceph RBD +- Gluster Volume +- Google Persistent Disk +- Longhorn +- Openstack Cinder Volume +- Portworx Volume +- Quobyte Volume +- ScaleIO Volume +- StorageOS +- Vmware vSphere Volume + +In addition to customizing each provisioner's options for the storage class, you can also define the volume `reclaimPolicy`. There are two options available: + +- Delete volumes and underlying device when released by workloads. +- Retain the volume for manual cleanup. + +Finally, you can define custom `MountOptions` for the persistent volume created. + +`parameters` are specific to each cloud storage provisioner. For full information about the storage classes provisioner parameters, refer to the official [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters). + +### Adding Storage Classes + +_Storage Classes_ allow you to dynamically provision persistent volumes on demand. Think of storage classes as storage profiles that are created automatically upon a request (which is known as a _persistent volume claim_). 1. From the **Global** view, open the cluster for which you want to dynamically provision persistent storage volumes. @@ -71,7 +118,7 @@ _Storage Classes_ allow you to dynamically provision persistent volumes on deman 1. From the `Provisioner` drop-down, select the service that you want to use to dynamically provision storage volumes. >**Note:** If the cluster you are adding a storage class for is a cloud service that also offers cloud storage, you must enable the `cloud provider` option for the cluster, and you must use the service's plug-in to use cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it: - + 1. You must enable the `cloud provider` option for the EC2 cluster. 2. You must use the `Amazon EBS Disk` provisioner. @@ -86,5 +133,11 @@ Mount Persistent Volumes to workloads so that your applications can store their You can mount Persistent Volumes in one of two contexts: -- During deployment of a workload (recommended if possible). For more information, see [Deploying Workloads](../../workloads/deploy-workloads/). -- Following workload creation. For more information, see [Adding Persistent Volume Claims](../../workloads/add-persistent-volume-claim/). \ No newline at end of file +- During deployment of a workload (recommended if possible). For more information, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/). +- Following workload creation. For more information, see [Adding Persistent Volume Claims]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/persistent-volume-claims/). + +## Related Links + +### External Docs + +- [Storage](https://kubernetes.io/docs/concepts/storage/) diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/_index.md similarity index 77% rename from content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/_index.md index e29fc390d43..26c4f07257a 100644 --- a/content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/_index.md @@ -1,6 +1,8 @@ --- -title: Provisioning Storage -weight: 3500 +title: Provisioning Storage Examples +weight: 3053 +aliases: + - /rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/ --- Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself. diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/nfs/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/nfs/_index.md similarity index 84% rename from content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/nfs/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/nfs/_index.md index ec4a49d4cf1..4ee35a50945 100644 --- a/content/rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/nfs/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/examples/nfs/_index.md @@ -1,13 +1,15 @@ --- -title: Provisioning NFS Storage -weight: 3500 +title: NFS Storage +weight: 3054 +aliases: + - /rancher/v2.x/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]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/). +>- 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]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/). > >- This procedure demonstrates how to setup 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. @@ -63,4 +65,4 @@ Before you can use the NFS storage volume plug-in with Rancher deployments, you ## What's Next? -Within Rancher, add the NFS server as a [storage volume]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/#adding-a-persistent-volume) and/or [storage class]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/#adding-storage-classes). After adding the server, you can use it for storage for your deployments. +Within Rancher, add the NFS server as a [storage volume]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/#adding-a-persistent-volume) and/or [storage class]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/#adding-storage-classes). After adding the server, you can use it for storage for your deployments. diff --git a/content/rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md similarity index 82% rename from content/rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md index 93ef3081f8b..0b694cba100 100644 --- a/content/rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md @@ -1,6 +1,8 @@ --- -title: Adding a Persistent Volume Claim -weight: 100 +title: Persistent Volume Claims +weight: 3052 +aliases: + - /rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim --- _Persistent Volume Claims_ (or PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. When you create a deployment, you should usually attach a PVC so that your application can lay claim to persistent storage. This claim lets your deployment application store its data in an external location, so that if one of the application's containers fails, it can be replaced with a new container and continue accessing its data stored externally, as though an outage never occured. @@ -10,7 +12,7 @@ _Persistent Volume Claims_ (or PVCs) are objects that request storage resources - Each Rancher project contains a list of PVCs that you've created, available from the **Volumes** tab. You can reuse these PVCs when creating deployments in the future. >**Prerequisite:** -> You must have a pre-provisioned [persistent volume]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/#adding-a-persistent-volume) available for use, or you must have a [storage class created]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/adding-storage/#adding-storage-classes) that dynamically creates a volume upon request from the workload. +> You must have a pre-provisioned [persistent volume]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/#adding-a-persistent-volume) available for use, or you must have a [storage class created]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/volumes-and-storage/#adding-storage-classes) that dynamically creates a volume upon request from the workload. 1. From the **Global** view, open the project containing a workload that you want to add a PVC to. @@ -39,4 +41,3 @@ _Persistent Volume Claims_ (or PVCs) are objects that request storage resources 7. **Optional:** From **Customize**, select the [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) that you want to use. **Result:** Your PVC is created. You can now attach it to any workload in the project. - diff --git a/content/rancher/v2.x/en/concepts/workloads/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/_index.md similarity index 88% rename from content/rancher/v2.x/en/concepts/workloads/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/workloads/_index.md index 7dfb09147a7..deed2bde4a7 100644 --- a/content/rancher/v2.x/en/concepts/workloads/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/_index.md @@ -1,7 +1,11 @@ --- title: Workloads -weight: 2175 +weight: 3025 +aliases: + - /rancher/v2.x/en/concepts/workloads/ + - /rancher/v2.x/en/tasks/workloads/ --- + You can build any complex containerized application in Kubernetes using two basic constructs: pods and workloads. Once you build an application, you can expose it for access either within the same cluster or on the Internet using a third construct: services. ### Pods @@ -43,7 +47,7 @@ In many use cases, a workload has to be either: - Accessed by other workloads in the cluster. - Exposed to the outside world. - + You can achieve these goals by creating a _Service_. Services are mapped to the underlying workload's pods using a [selector/label approach (view the code samples)](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#service-and-replicationcontroller). Rancher UI simplifies this mapping process by automatically creating a service along with the workload, using the service port and type that you select. #### Service Types @@ -62,12 +66,16 @@ There are several types of services available in Rancher. The descriptions below >Exposes the service externally using a cloud provider’s load balancer. `NodePort` and `ClusterIP` services, to which the external load balancer will route, are automatically created. +## Workload Options + +This section of the documentation contains instructions for deploying workloads and using workload options. + + - [Deploy Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/) + - [Upgrade Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/upgrade-workloads/) + - [Rollback Workloads]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/rollback-workloads/) + ## Related Links ### External Links - [Services](https://kubernetes.io/docs/concepts/services-networking/service/) - -### Tutorials - -- [Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/) diff --git a/content/rancher/v2.x/en/tasks/workloads/add-a-sidecar/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/add-a-sidecar/_index.md similarity index 95% rename from content/rancher/v2.x/en/tasks/workloads/add-a-sidecar/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/workloads/add-a-sidecar/_index.md index a044732e71f..e5c6c4f503e 100644 --- a/content/rancher/v2.x/en/tasks/workloads/add-a-sidecar/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/add-a-sidecar/_index.md @@ -1,6 +1,8 @@ --- title: Adding a Sidecar -weight: 200 +weight: 3029 +aliases: + - /rancher/v2.x/en/tasks/workloads/add-a-sidecar/ --- A _sidecar_ is a container that extends or enhances the main container in a pod. The main container and the sidecar share a pod, and therefore share the same network space and storage. You can add sidecars to existing workloads by using the **Add a Sidecar** option. @@ -15,11 +17,11 @@ A _sidecar_ is a container that extends or enhances the main container in a pod. 1. Select a **Sidecar Type**. This option determines if the sidecar container is deployed before or after the main container is deployed. - **Standard Container:** - + The sidecar container is deployed after the main container. - **Init Container:** - + The sidecar container is deployed before the main container. 1. From the **Docker Image** field, enter the name of the Docker image that you want to deploy in support of the main container. During deployment, Rancher pulls this image from [Docker Hub](https://hub.docker.com/explore/). Enter the name exactly as it appears on Docker Hub. diff --git a/content/rancher/v2.x/en/tasks/workloads/deploy-workloads/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/_index.md similarity index 79% rename from content/rancher/v2.x/en/tasks/workloads/deploy-workloads/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/_index.md index dd628ed2a90..8cf3dfd3ea9 100644 --- a/content/rancher/v2.x/en/tasks/workloads/deploy-workloads/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/deploy-workloads/_index.md @@ -1,6 +1,8 @@ --- title: Deploying Workloads -weight: 25 +weight: 3026 +aliases: + - /rancher/v2.x/en/tasks/workloads/deploy-workloads/ --- Deploy a workload to run an application in one or more containers. @@ -11,25 +13,25 @@ Deploy a workload to run an application in one or more containers. 1. Enter a **Name** for the workload. -1. Select a [workload type]({{< baseurl >}}/rancher/v2.x/en/concepts/workloads/). The workload defaults to a scalable deployment, by can change the workload type by clicking **More options.** +1. Select a [workload type]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/). The workload defaults to a scalable deployment, by can change the workload type by clicking **More options.** 1. From the **Docker Image** field, enter the name of the Docker image that you want to deploy to the project. During deployment, Rancher pulls this image from [Docker Hub](https://hub.docker.com/explore/). Enter the name exactly as it appears on Docker Hub. 1. Either select an existing [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), or click **Add to a new namespace** and enter a new namespace. -1. Click **Add Port** to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see [Services]({{< baseurl >}}/rancher/v2.x/en/concepts/workloads/#services). +1. Click **Add Port** to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see [Services]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/workloads/#services). 1. Configure the remaining options: - **Environment Variables** - Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or [ConfigMap]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-configmaps/). + Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or [ConfigMap]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/configmaps/). - **Node Scheduling** - **Health Check** - **Volumes** - Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a [ConfigMap]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-configmaps/). + Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a [ConfigMap]({{< baseurl >}}/rancher/v2.x/en/kubernetes-in-rancher/configmaps/). - **Scaling/Upgrade Policy** @@ -39,7 +41,7 @@ Deploy a workload to run an application in one or more containers. > >- In [Amazon AWS](https://aws.amazon.com/), the nodes must be in the same Availability Zone and possess IAM permissions to attach/unattach volumes. > - >- The cluster must be using the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws) option. For more information on enabling this option see [Creating an Amazon EC2 Cluster]({{< baseurl >}}/rancher/v2.x/en/clusters/rke-clusters/node-pools/ec2/) or [Creating a Custom Cluster]({{< baseurl >}}/rancher/v2.x/en/clusters/custom-clusters/). + >- The cluster must be using the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws) option. For more information on enabling this option see [Creating an Amazon EC2 Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/) or [Creating a Custom Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/). 1. Click **Show Advanced Options** and configure: diff --git a/content/rancher/v2.x/en/tasks/workloads/rollback-workloads/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/rollback-workloads/_index.md similarity index 88% rename from content/rancher/v2.x/en/tasks/workloads/rollback-workloads/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/workloads/rollback-workloads/_index.md index 0c83bdb1993..a10bcea6ebd 100644 --- a/content/rancher/v2.x/en/tasks/workloads/rollback-workloads/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/rollback-workloads/_index.md @@ -1,6 +1,8 @@ --- title: Rolling Back Workloads -weight: 150 +weight: 3027 +aliases: + - /rancher/v2.x/en/tasks/workloads/rollback-workloads/ --- Sometimes there is a need to rollback to the previous version of the application, either for debugging purposes or because an upgrade did not go as planned. diff --git a/content/rancher/v2.x/en/tasks/workloads/upgrade-workloads/_index.md b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/upgrade-workloads/_index.md similarity index 93% rename from content/rancher/v2.x/en/tasks/workloads/upgrade-workloads/_index.md rename to content/rancher/v2.x/en/kubernetes-in-rancher/workloads/upgrade-workloads/_index.md index 0a7882d990f..c00c15e0a97 100644 --- a/content/rancher/v2.x/en/tasks/workloads/upgrade-workloads/_index.md +++ b/content/rancher/v2.x/en/kubernetes-in-rancher/workloads/upgrade-workloads/_index.md @@ -1,6 +1,8 @@ --- title: Upgrading Workloads -weight: 125 +weight: 3028 +aliases: + - /rancher/v2.x/en/tasks/workloads/upgrade-workloads/ --- When a new version of an application image is released on Docker Hub, you can upgrade any workloads running a previous version of the application to the new one. diff --git a/content/rancher/v2.x/en/tasks/_index.md b/content/rancher/v2.x/en/tasks/_index.md deleted file mode 100644 index ae1250144c6..00000000000 --- a/content/rancher/v2.x/en/tasks/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Tutorials -weight: 3000 ---- -This section of the docs provide step-by-step instructions on how to accomplish a goal within Rancher. diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-a-node/_index.md b/content/rancher/v2.x/en/tasks/clusters/adding-a-node/_index.md deleted file mode 100644 index 22b6749fc45..00000000000 --- a/content/rancher/v2.x/en/tasks/clusters/adding-a-node/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Adding a Node -weight: 3475 -draft: true ---- -Coming Soon - -## By Node/Cloud Provider - -Coming Soon - -## By Custom - -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-a-pod-security-policy/_index.md b/content/rancher/v2.x/en/tasks/clusters/adding-a-pod-security-policy/_index.md deleted file mode 100644 index 6bbd2ef58c9..00000000000 --- a/content/rancher/v2.x/en/tasks/clusters/adding-a-pod-security-policy/_index.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Adding a Pod Security Policy -weight: 3475 ---- - -_Pod Security Policies_ are objects that control security-sensitive aspects of pod specification (like root privileges). - -You can add a Pod Security Policy (PSPs hereafter) in the following contexts: - -- [When creating a cluster](#cluster-creation--adding-a-default-pod-security-policy) -- [When editing an existing cluster](#existing-cluster--adding-a-pod-security-policy) -- [When creating a project](#project-creation--adding-a-pod-security-policy) -- [When editing an existing project](#existing-project--adding-a-pod-security-policy) - -> **Note:** We recommend adding PSPs during cluster and project creation instead of adding it to an existing one. - -For more information about PSPs, refer to [Pod Security Policy]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies). - -## Cluster Creation: Adding a Default Pod Security Policy - -When you create a new cluster, you can configure it to apply a PSP immediately. As you create the cluster, use the **Cluster Options** to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster. - ->**Prerequisite:** ->Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). ->**Note:** ->For security purposes, we recommend assigning a PSP as you create your clusters. - -To enable a default Pod Security Policy, set the **Pod Security Policy Support** option to **Enabled**, and then make a selection from the **Default Pod Security Policy** drop-down. - -When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster. - -For detailed instruction about assigning a PSP to a new cluster, see [Creating a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/). - -## Existing Cluster: Adding a Pod Security Policy - -If you don't apply a PSP as you create your cluster, you can always add one later. - ->**Prerequisite:** ->Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). - -1. From the **Global** view, find the cluster that you want to apply your PSP to. Select **Vertical Ellipsis (...) > Edit** for the cluster you want to enable PSPs for. - -2. Expand the **Cluster Options** accordion. - -3. From **Pod Security Policy Support**, select **Enabled**. - - >**Note:** Not all cluster providers support PSPs, so this option may not be available. - - **Step Result:** The **Default Pod Security Policy** drop-down activates. - -4. From **Default Pod Security Policy**, select the PSP you want to apply to the cluster. - -5. Click **Save**. - -**Result:** The PSP is applied to the cluster and any projects within the cluster. - ->**Note:** 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. - -## Project Creation: Adding a Pod Security Policy - -When you create a new project, you can assign a PSP directly 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. - ->**Prerequisites:** -> -> - Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). -> - Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [Existing Cluster: Adding a Pod Security Policy](#existing-cluster--adding-a-pod-security-policy). - -As you create the project, make a selection from the **Pod Security Policy** drop-down to assign a PSP. - - - -## Existing Project: Adding a Pod Security Policy - -You can always assign a PSP to an existing project if you didn't assign one during creation. - ->**Prerequisites:** -> -> - Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/). -> - Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [Existing Cluster: Adding a Pod Security Policy](#existing-cluster--adding-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**. - -3. Find the project that you want to add a PSP to. From that project, select **Vertical Ellipsis (...) > Edit**. - -4. From the **Pod Security Policy** drop-down, select the PSP you want to apply to the project. - -5. 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 if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP. diff --git a/content/rancher/v2.x/en/tasks/clusters/adding-managing-cluster-members/_index.md b/content/rancher/v2.x/en/tasks/clusters/adding-managing-cluster-members/_index.md deleted file mode 100644 index 57d7b0a8c19..00000000000 --- a/content/rancher/v2.x/en/tasks/clusters/adding-managing-cluster-members/_index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Adding Cluster Members -weight: 3525 ---- - -If you want to provide a user with access and permissions to _all_ projects, nodes, and resources within a cluster, assign the user a cluster membership. - ->**Tip:** Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/add-project-members/) instead. - -There are two contexts where you can add cluster members: - -- [Adding Members to a New Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster) - - You can add members to a cluster as you create it (recommended if possible). - -- [Adding Members to an Existing Cluster](#adding-members-to-an-existing-cluster) - - You can always add members to a cluster later. See below. - -### Adding Members to an Existing Cluster - -Following cluster creation, you can add users as cluster members so that they can access its resources. - -1. From the **Global** view, open the cluster that you want to add members to. - -2. From the main menu, select **Members**. Then click **Add Member**. - -3. Search for the user or group that you want to add to the cluster. - - If external authentication is configured: - - - Rancher returns users from your [external authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) source as you type. - - >**Using AD but can't find your users?** - >There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/configuring-ad/). - - - A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of. - - >**Note:** If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users). - -4. Assign the user or group **Cluster** roles. - - [What are Cluster Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#cluster-roles) - - >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. - > - > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/creating-roles/#adding-a-custom-role). - > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/creating-roles/#locking-unlocking-roles). - -**Result:** The chosen users are added to the cluster. - -- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user. -- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles. \ No newline at end of file diff --git a/content/rancher/v2.x/en/tasks/projects/_index.md b/content/rancher/v2.x/en/tasks/projects/_index.md deleted file mode 100644 index 43214fef9d8..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Projects -weight: 3650 -draft: true ---- -_Projects_ are a new feature in Rancher that allows you to group namespaces. Users can be added as members to the project, and the project owner can assign roles to each member to control their project access. diff --git a/content/rancher/v2.x/en/tasks/projects/add-project-alerts/_index.md b/content/rancher/v2.x/en/tasks/projects/add-project-alerts/_index.md deleted file mode 100644 index 84eae19507d..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/add-project-alerts/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Adding Project Alerts -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/add-project-members/_index.md b/content/rancher/v2.x/en/tasks/projects/add-project-members/_index.md deleted file mode 100644 index 04046b75e43..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/add-project-members/_index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Adding Project Members -weight: ---- - -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. - ->**Tip:** Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members]({{< baseurl >}}/rancher/v2.x/en/clusters/adding-users) instead. - -There are two contexts where you can add project members: - -- [Adding Members to a New Project]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/create-project) - - You can add members to a project as you create it (recommended if possible). - -- [Adding Members to an Existing Project](#adding-members-to-an-existing-project) - - You can always add members to a project later. See below. - -### Adding Members to an Existing project - -Following project creation, you can add users as project members so that they can access its resources. - -1. From the **Global** view, open the project that you want to add members to. - -2. From the main menu, select **Members**. Then click **Add Member**. - -3. Search for the user or group that you want to add to the project. - - If external authentication is configured: - - - Rancher returns users from your external authentication source as you type. - - - A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in. - - >**Note:** If you are logged in as a local user, external users do not display in your search results. - -1. Assign the user or group **Project** roles. - - [What are Project Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#cluster-roles) - - >**Tip:** For Custom Roles, you can modify the list of individual roles available for assignment. - > - > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/creating-roles/#adding-a-custom-role). - > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/creating-roles/#locking-unlocking-roles). - -**Result:** The chosen users are added to the project. - -- To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user. -- To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles. diff --git a/content/rancher/v2.x/en/tasks/projects/create-pod-security-policies/_index.md b/content/rancher/v2.x/en/tasks/projects/create-pod-security-policies/_index.md deleted file mode 100644 index 70308048c88..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/create-pod-security-policies/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Creating Pod Security Policies -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/create-project/_index.md b/content/rancher/v2.x/en/tasks/projects/create-project/_index.md deleted file mode 100644 index 8fb7c996ec6..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/create-project/_index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Creating Projects -weight: ---- - -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**. - -1. **Optional:** Select a **Pod Security Policy**. - - [What are Pod Security Policies?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies) - - >**Note:** This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#creating-pod-security-policies). - -1. **Recommended:** Add project members. - - Use the **Members** accordion to provide other users with project access and roles. - - By default, your user is added as the project `Owner`. - - 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. - - [What are Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#cluster-and-project-roles) - - >**Tip:** Choose Custom to create a custom role on the fly: [Custom Project Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#custom-project-roles). - - 1. To add more members, repeat substeps a—c. - - -1. Click **Create**. - -**Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view. \ No newline at end of file diff --git a/content/rancher/v2.x/en/tasks/projects/enable-project-logging/_index.md b/content/rancher/v2.x/en/tasks/projects/enable-project-logging/_index.md deleted file mode 100644 index 0f02a92be43..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/enable-project-logging/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Enabling Project Logging -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/launch-a-catalog-app/_index.md b/content/rancher/v2.x/en/tasks/projects/launch-a-catalog-app/_index.md deleted file mode 100644 index 47da8f3b928..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/launch-a-catalog-app/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Launching a Catalog App -weight: -draft: true ---- -After you've enabled default catalogs or setup a custom catalog, you can launch apps using a catalog instead of a standard deployment. - ->**Prerequisite:** Enable a catalog. For more information, see [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs). - -1. From the **Global** view, open the project that you want to deploy to. - -2. From the main menu, choose **Catalog Apps**. Then click **Launch**. - -3. Find the app that you want to launch, and then click **View Now**. - -4. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application. - - * If you would like to change the **Namespace**, click **Customize** and enter a new name. - * If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list. - -5. Select a **Template Version**. - -6. Complete the rest of the **Configuration Options**. - - * For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section. - * Keys and values are available within **Detailed Descriptions**. - -7. Review the files in **Preview**. When you're satisfied, click **Launch**. - -**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's: - -- **Workloads** view -- **Catalog Apps** view diff --git a/content/rancher/v2.x/en/tasks/projects/manage-pod-security-policies/_index.md b/content/rancher/v2.x/en/tasks/projects/manage-pod-security-policies/_index.md deleted file mode 100644 index 9da1ef07f4f..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/manage-pod-security-policies/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Managing Pod Security Policies -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/manage-project-alerts/_index.md b/content/rancher/v2.x/en/tasks/projects/manage-project-alerts/_index.md deleted file mode 100644 index 9a2ce2dcde6..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/manage-project-alerts/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Managing Project Alerts -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/manage-project-logging/_index.md b/content/rancher/v2.x/en/tasks/projects/manage-project-logging/_index.md deleted file mode 100644 index 2ff795cd31f..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/manage-project-logging/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Managing Project Logging -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/manage-project-members/_index.md b/content/rancher/v2.x/en/tasks/projects/manage-project-members/_index.md deleted file mode 100644 index 3ca33000d8c..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/manage-project-members/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Managing Project Members -weight: -draft: true ---- -Coming Soon diff --git a/content/rancher/v2.x/en/tasks/projects/switch-project/_index.md b/content/rancher/v2.x/en/tasks/projects/switch-project/_index.md deleted file mode 100644 index f7ab9fdb8eb..00000000000 --- a/content/rancher/v2.x/en/tasks/projects/switch-project/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Switching Projects (and Clusters) -weight: -draft: true ---- - -To switch between clusters, use the **Global** drop-down available in the main menu. - -![Global Menu]({{< baseurl >}}/img/rancher/global-menu.png) - -Alternatively, you can switch between projects and clusters using the main menu. - -- To switch between clusters, open the **Global** view and select **Clusters** from the main menu. Then open a cluster. -- To switch between projects, open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open. \ No newline at end of file diff --git a/content/rancher/v2.x/en/tasks/workloads/_index.md b/content/rancher/v2.x/en/tasks/workloads/_index.md deleted file mode 100644 index 9f174b46aca..00000000000 --- a/content/rancher/v2.x/en/tasks/workloads/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Workloads -weight: 3675 ---- - -This section of the documentation contains instructions for deploying workloads and using workload options. - -- [Deploy Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/deploy-workloads/) -- [Upgrade Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/upgrade-workloads/) -- [Rollback Workloads]({{< baseurl >}}/rancher/v2.x/en/tasks/workloads/rollback-workloads/) diff --git a/content/rancher/v2.x/en/user-settings/api-keys/_index.md b/content/rancher/v2.x/en/user-settings/api-keys/_index.md index 02f032a5183..26e80c52374 100644 --- a/content/rancher/v2.x/en/user-settings/api-keys/_index.md +++ b/content/rancher/v2.x/en/user-settings/api-keys/_index.md @@ -1,5 +1,5 @@ --- -title: Creating an API Key +title: API Keys weight: 7005 aliases: - /rancher/v2.x/en/concepts/api-keys/ diff --git a/layouts/shortcodes/beta-note_azure.html b/layouts/shortcodes/beta-note_azure.html index 45bc678961a..3ad381dde2f 100644 --- a/layouts/shortcodes/beta-note_azure.html +++ b/layouts/shortcodes/beta-note_azure.html @@ -1,4 +1,4 @@
Note: -

As of Rancher v2.0 GA, the Azure Container Service option is still in beta.

+

As of Rancher v2.0 GA, the Azure Kubernetes Service option is still in beta.

diff --git a/layouts/shortcodes/requirements_ports_rancher.html b/layouts/shortcodes/requirements_ports_rancher.html index 4d4263990f6..62d2297d16e 100644 --- a/layouts/shortcodes/requirements_ports_rancher.html +++ b/layouts/shortcodes/requirements_ports_rancher.html @@ -41,6 +41,12 @@
  • 35.160.43.145/32
  • 35.167.242.46/32
  • 52.33.59.17/32
    • git.rancher.io (catalogs) + + TCP + 2376 +
    • Any node IP from a node created using Node Driver
      • + Docker daemon TLS port used by Docker Machine + TCP 6443 diff --git a/layouts/shortcodes/requirements_ports_rke.html b/layouts/shortcodes/requirements_ports_rke.html index f5b0491a08a..01b76d194fc 100644 --- a/layouts/shortcodes/requirements_ports_rke.html +++ b/layouts/shortcodes/requirements_ports_rke.html @@ -8,6 +8,12 @@ Source Description + + TCP + 2376 +
      • Rancher nodes
        • + Docker daemon TLS port used by Docker Machine
        (only needed when using Node Driver/Templates) + TCP 2379 @@ -105,6 +111,12 @@
        • Any that consumes Ingress services
        Ingress controller (HTTPS) + + TCP + 2376 +
        • Rancher nodes
          • + Docker daemon TLS port used by Docker Machine
          (only needed when using Node Driver/Templates) + TCP 6443 @@ -214,6 +226,12 @@
          • Any that consumes Ingress services
          Ingress controller (HTTPS) + + TCP + 2376 +
          • Rancher nodes
            • + Docker daemon TLS port used by Docker Machine
            (only needed when using Node Driver/Templates) + UDP 8472 diff --git a/layouts/shortcodes/step_create-cluster_cluster-options.html b/layouts/shortcodes/step_create-cluster_cluster-options.html index 28064c50abd..5e15db10ed1 100644 --- a/layouts/shortcodes/step_create-cluster_cluster-options.html +++ b/layouts/shortcodes/step_create-cluster_cluster-options.html @@ -1 +1 @@ -

            Use Cluster Options to choose the version of Kubernetes installed on each cluster node, along with some other options for you cluster.

            +

            Use Cluster Options to choose the version of Kubernetes, what network provider will be used, if you want to enable Pod Security Policies and wether the nodes added to this cluster need to have a supported Docker version installed. diff --git a/layouts/shortcodes/step_create-cluster_node-pools.html b/layouts/shortcodes/step_create-cluster_node-pools.html index 7b3154d378f..984765e6f5d 100644 --- a/layouts/shortcodes/step_create-cluster_node-pools.html +++ b/layouts/shortcodes/step_create-cluster_node-pools.html @@ -1,10 +1,10 @@ -

            Add one or more Node Pools to your cluster. A node pool is a set of virtual machines configured identically to your Linux host. However, each node in the pool also has additional Kubernetes master and worker components installed.

            +

            Add one or more Node Pools to your cluster.

            A Node Pool is a collection of nodes based on a Node Template. A Node Template defines the configuration of a Node, like what Operating System image, number of CPUs and amount of RAM. Each Node Pool can have one or more Nodes Roles associated with it.

            Notes:

              -
            • After you create each node template, you can use it to create additional node pools.
              • -
            • Each Kubernetes role (i.e. etcd, Control, and Worker) must be filled. You can either apply all three roles to one pool or spread them around.
              • -
            • Ideally, you should have at least three etcd nodes so that your cluster can fail over to another if a etcd node goes down.
              • +
            • After you create a Node Template, it will be saved and you will be able to re-use it in additional Node Pools.
              • +
            • Each Node Role (i.e. etcd, Control Plane, and Worker) must be fulfilled. Although it is possible to apply multiple Node Roles to a Node Pool, this is not recommended.
              • +
            • The recommended setup is to have a Node Pool with the etcd Node Role and a count of three, a Node Pool with the Control Plane Node Role and a count of at least two, and a Node Pool with the Worker Node Role and a count of at least two. Regarding the etcd Node Role, refer to the etcd Admin Guide.
            diff --git a/layouts/shortcodes/step_rancher-template.html b/layouts/shortcodes/step_rancher-template.html index d17c5be1616..859cff143f0 100644 --- a/layouts/shortcodes/step_rancher-template.html +++ b/layouts/shortcodes/step_rancher-template.html @@ -1,13 +1,18 @@ -

            Complete the Rancher Template form to add metadata so that you can find your template in Rancher later.

            +

            Complete the Rancher Template form to configure the Docker daemon on the instances that will be created.

            • -

              Labels apply metadata to your Docker objects.

              +

              Labels can be configured on the Docker daemon.

              Docker object label documentation

            • -

              Engine Options customize the configuration of the Docker daemon.

              +

              Engine Options customize the configuration of the Docker daemon. Important configuration options might include: +

                +
              • Docker Engine Install URL: Determines what Docker version will be installed on the instance.
                • +
              • Registry mirrors: Docker Registry mirror to be used by the Docker daemon
                • +
              +

              daemon option reference

              • diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 2aaa8250dda..00000000000 --- a/netlify.toml +++ /dev/null @@ -1,13 +0,0 @@ -[build] - command = "npm run build" - publish = "public" - -[build.environment] - HUGO_VERSION = "0.36" - -[context.production.environment] - HUGO_ENV = "production" - NODE_ENV = "production" - -[context.deploy-preview] - command = "npm run build:preview" diff --git a/src/img/rancher/ldapsearch-group.png b/src/img/rancher/ldapsearch-group.png new file mode 100644 index 00000000000..f92a95464b5 Binary files /dev/null and b/src/img/rancher/ldapsearch-group.png differ diff --git a/src/img/rancher/ldapsearch-user.png b/src/img/rancher/ldapsearch-user.png new file mode 100644 index 00000000000..594d9771241 Binary files /dev/null and b/src/img/rancher/ldapsearch-user.png differ