diff --git a/content/os/v1.x/en/installation/configuration/running-commands/_index.md b/content/os/v1.x/en/installation/configuration/running-commands/_index.md index 01bc8047343..11b8d44d8be 100644 --- a/content/os/v1.x/en/installation/configuration/running-commands/_index.md +++ b/content/os/v1.x/en/installation/configuration/running-commands/_index.md @@ -12,7 +12,7 @@ runcmd: - echo "test" > /home/rancher/test2 ``` -Commands specified using `runcmd` will be executed within the context of the `console` container. More details on the ordering of commands run in the `console` container can be found [here]({{< baseurl >}}/os/v1.x/en/installation/boot-process/built-in-system-services/#console). +Commands specified using `runcmd` will be executed within the context of the `console` container. ### Running Docker commands diff --git a/content/rancher/v2.x/en/admin-settings/_index.md b/content/rancher/v2.x/en/admin-settings/_index.md index 86fc30a3512..87ae8b08a3a 100644 --- a/content/rancher/v2.x/en/admin-settings/_index.md +++ b/content/rancher/v2.x/en/admin-settings/_index.md @@ -46,16 +46,16 @@ For more information, see [Provisioning Drivers]({{< baseurl >}}/rancher/v2.x/en _Available as of v2.3.0_ -With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions. +With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions. The information that Rancher uses to provision [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rke-metadata/). Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). -For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata]({{}}/rancher/v2.x/en/admin-settings/k8s-metadata). +For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata]({{}}/rancher/v2.x/en/admin-settings/k8s-metadata/). ## Enabling Experimental Features _Available as of v2.3.0_ -Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about [feature flags.]({{}}/rancher/v2.x/en/installation/options/feature-flags) +Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about [feature flags.]({{}}/rancher/v2.x/en/admin-settings/feature-flags/) diff --git a/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md index 68f4f3c9cab..8bfc1edf915 100644 --- a/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md +++ b/content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md @@ -2,70 +2,166 @@ 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. Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access. ->**Prerequisites:** -> ->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/global-permissions/#custom-global-permissions) with the [Manage Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. +This section covers the following topics: -## Adding A Custom Role +- [Prerequisites](#prerequisites) +- [Creating a custom role for a cluster or project](#creating-a-custom-role-for-a-cluster-or-project) +- [Creating a custom global role that copies rules from an existing role](#creating-a-custom-global-role-that-copies-rules-from-an-existing-role) +- [Creating a custom global role that does not copy rules from another role](#creating-a-custom-global-role-that-does-not-copy-rules-from-another-role) +- [Deleting a custom global role](#deleting-a-custom-global-role) +- [Assigning a custom global role to a group](#assigning-a-custom-global-role-to-a-group) + +## Prerequisites + +To complete the tasks on this page, one of the following permissions are required: + + - [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/). + - [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. + +## Creating A Custom Role for a Cluster or Project While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher. -1. From the **Global** view, select **Security > Roles** from the main menu. +The steps to add custom roles differ depending on the version of Rancher. -1. **v2.0.7 and later only:** Select a tab to determine the scope of the roles you're adding. The tabs are: +{{% tabs %}} +{{% tab "Rancher v2.0.7+" %}} - - **Cluster** +1. From the **Global** view, select **Security > Roles** from the main menu. - The role is valid for assignment when adding/managing members to _only_ clusters. +1. Select a tab to determine the scope of the roles you're adding. The tabs are: - - **Project** + - **Cluster:** The role is valid for assignment when adding/managing members to _only_ clusters. + - **Project:** The role is valid for assignment when adding/managing members to _only_ projects. - The role is valid for assignment when adding/managing members to _only_ projects. +1. Click **Add Cluster/Project Role.** - >**Note:** You cannot edit the Global tab. +1. **Name** the role. -1. Click **Add Cluster/Project Role**. +1. Optional: Choose the **Cluster/Project Creator Default** option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators. -1. **Name** the role. + > Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively. -1. Choose whether to set the role to a status of [locked]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/). +1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role. - Locked roles cannot be assigned to users. + > When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. -1. **v2.0.7 and later only:** Choose a **Cluster/Project Creator Default** option setting. Use this option to set if the role is assigned to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators. + You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign. - >**Note:** Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively. +1. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted. -1. **v2.0.6 and earlier only:** Assign the role a **Context**. Context determines the scope of role assigned to the user. The contexts are: +1. Click **Create**. - - **All** +{{% /tab %}} +{{% tab "Rancher prior to v2.0.7" %}} - The user can use their assigned role regardless of context. This role is valid for assignment when adding/managing members to clusters or projects. +1. From the **Global** view, select **Security > Roles** from the main menu. - - **Cluster** +1. Click **Add Role**. - This role is valid for assignment when adding/managing members to _only_ clusters. +1. **Name** the role. - - **Project** +1. Choose whether to set the role to a status of [locked]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/). - This role is valid for assignment when adding/managing members to _only_ projects. + > **Note:** Locked roles cannot be assigned to users. -6. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role. +1. In the **Context** dropdown menu, choose the scope of the role assigned to the user. The contexts are: - >**Note:** When viewing the resources associated with default roles created by Rancher, if there are multiple Kuberenetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + - **All:** The user can use their assigned role regardless of context. This role is valid for assignment when adding/managing members to clusters or projects. - You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign. + - **Cluster:** This role is valid for assignment when adding/managing members to _only_ clusters. -7. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. + - **Project:** This role is valid for assignment when adding/managing members to _only_ projects. -8. Click **Create**. +1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role. + + > When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + + You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign. + +1. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted. + +1. Click **Create**. + +{{% /tab %}} +{{% /tabs %}} + +## Creating a Custom Global Role that Copies Rules from an Existing Role + +_Available as of v2.4_ + +If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role. + +The custom global role can then be assigned to a user or group so that the custom global role takes effect the first time the user or users sign into Rancher. + +To create a custom global role based on an existing role, + +1. Go to the **Global** view and click **Security > Roles.** +1. On the **Global** tab, go to the role that the custom global role will be based on. Click **Ellipsis (…) > Clone.** +1. Enter a name for the role. +1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.** +1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role. +1. Click **Save.** + +## Creating a Custom Global Role that Does Not Copy Rules from Another Role + +_Available as of v2.4_ + +Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps: + +1. Go to the **Global** view and click **Security > Roles.** +1. On the **Global** tab, click **Add Global Role.** +1. Enter a name for the role. +1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.** +1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role. +1. Click **Save.** + +## Deleting a Custom Global Role + +_Available as of v2.4_ + +When deleting a custom global role, all global role bindings with this custom role are deleted. + +If a user is only assigned one custom global role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions. + +Custom global roles can be deleted, but built-in roles cannot be deleted. + +To delete a custom global role, + +1. Go to the **Global** view and click **Security > Roles.** +2. On the **Global** tab, go to the custom global role that should be deleted and click **Ellipsis (…) > Delete.** +3. Click **Delete.** + +## Assigning a Custom Global Role to a Group + +_Available as of v2.4_ + +If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher. + +When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups. + +If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have their individual Standard User role. + +> **Prerequisites:** You can only assign a global role to a group if: +> +> * You have set up an [external authentication provider]({{}}/rancher/v2.x/en/admin-settings/authentication/#external-vs-local-authentication) +> * The external authentication provider suppports [user groups]({{}}/rancher/v2.x/en/admin-settings/authentication/user-groups/) +> * You have already set up at least one user group with the authentication provider + +To assign a custom global role to a group, follow these steps: + +1. From the **Global** view, go to **Security > Groups.** +1. Click **Assign Global Role.** +1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role. +1. In the **Custom** section, choose any custom global role that will be assigned to the group. +1. Optional: In the **Global Permissions** or **Built-in** sections, select any additional permissions that the group should have. +1. Click **Create.** + +**Result:** The custom global role will take effect when the users in the group log into Rancher. \ No newline at end of file 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 index 829f579537e..f66580a89f4 100644 --- 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 @@ -7,43 +7,59 @@ _Permissions_ are individual access rights that you can assign when selecting a 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:** +- **Administrator:** These users have full control over the entire Rancher system and all clusters within it. - 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. -- **Standard User:** +You cannot update or delete the built-in Global Permissions. - These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters. +This section covers the following topics: ->**Note:** You cannot create, update, or delete Global Permissions. +- [Global permission assignment](#global-permission-assignment) + - [Global permissions for new local users](#global-permissions-for-new-local-users) + - [Global permissions for users with external authentication](#global-permissions-for-users-with-external-authentication) +- [Custom global permissions](#custom-global-permissions) + - [Custom global permissions reference](#custom-global-permissions-reference) + - [Configuring default global permissions for new users](#configuring-default-global-permissions) + - [Configuring global permissions for existing individual users](#configuring-global-permissions-for-existing-individual-users) + - [Configuring global permissions for groups](#configuring-global-permissions-for-groups) + - [Refreshing group memberships](#refreshing-group-memberships) # Global Permission Assignment -Assignment of global permissions to a user depends on their authentication source: external or local. +Global permissions for local users are assigned differently than users who log in to Rancher using external authentication. -- **External Authentication** +### Global Permissions for New Local Users - When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the `Standard User` global permission. +When you create a new local user, you assign them a global permission as you complete the **Add User** form. -- **Local Authentication** +To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column. You can [change the default global permissions to meet your needs.](#configuring-default-global-permissions) - When you create a new local user, you assign them a global permission as you complete the **Add User** form. +### Global Permissions for Users with External Authentication + +When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the **New User Default** global permissions. By default, Rancher assigns the **Standard User** permission for new users. + +To see the default permissions for new users, go to the **Global** view and click **Security > Roles.** On the **Global** tab, there is a column named **New User Default.** When adding a new local user, the user receives all default global permissions that are marked as checked in this column, and you can [change them to meet your needs.](#configuring-default-global-permissions) + +Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users) + +As of Rancher v2.4, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups. # Custom Global Permissions Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. -When a user from an [external authentication source]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in from the first time, they are created as a user and assigned the default `user` permission. The standard `user` permission allows users to login and create clusters. +When a user from an [external authentication source]({{}}/rancher/v2.x/en/admin-settings/authentication/) signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default `user` permission. The standard `user` permission allows users to login and create clusters. However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a more restrictive set of custom global permissions. The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role. -Administrators can enforce custom global permissions in two ways: +Administrators can enforce custom global permissions in multiple ways: -- Changing the [default permissions for new users](#configuring-default-global-permissions) - -- Editing the [permissions of an existing user](#configuring-global-permissions-for-individual-users) +- [Changing the default permissions for new users](#configuring-default-global-permissions) +- [Editing the permissions of an existing user](#configuring-global-permissions-for-individual-users) +- [Assigning a custom global permission to a group](#assigning-a-custom-global-permission-to-a-group) ### Custom Global Permissions Reference @@ -62,25 +78,25 @@ The following table lists each custom global permission available and whether it | Manage Settings | ✓ | | | Manage Users | ✓ | | | Use Catalog Templates | ✓ | ✓ | -| User Base* (Basic log-in access) | ✓ | ✓ | +| User Base\* (Basic log-in access) | ✓ | ✓ | -> *This role has two names: +> \*This role has two names: > > - When you go to the Users tab and edit a user's global role, this role is called Login Access in the custom global permissions list. > - When you go to the Security tab and edit the roles from the roles page, this role is called User Base. For details on which Kubernetes resources correspond to each global permission, you can go to the **Global** view in the Rancher UI. Then click **Security > Roles** and go to the **Global** tab. If you click an individual role, you can refer to the **Grant Resources** table to see all of the operations and resources that are permitted by the role. -> **Notes:** +> **Notes:** > ->- Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`. ->- When viewing the resources associated with default roles created by Rancher, if there are multiple Kuberenetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. +> - Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`. +> - When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. ### Configuring Default Global Permissions If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions. ->**Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user. +> **Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user. To change the default global permissions that are assigned to external users upon their first log in, follow these steps: @@ -94,7 +110,7 @@ To change the default global permissions that are assigned to external users upo **Result:** The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the **New User Default** column. -### Configuring Global Permissions for Individual Users +### Configuring Global Permissions for Existing Individual Users To configure permission for a user, @@ -109,3 +125,48 @@ To configure permission for a user, 1. Click **Save.** > **Result:** The user's global permissions have been updated. + +### Configuring Global Permissions for Groups + +_Available as of v2.4_ + +If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher. + +After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher. + +For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator [refreshes the group memberships.](#refreshing-group-memberships) + +For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the **New User Default** global permissions. By default, the **New User Default** permissions are equivalent to the **Standard User** global role, but the default permissions can be [configured.](#configuring-default-global-permissions) + +If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default.** Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,]((#refreshing-group-memberships)) whichever comes first. + +> **Prerequisites:** You can only assign a global role to a group if: +> +> * You have set up an [external authentication provider]({{}}/rancher/v2.x/en/admin-settings/authentication/#external-vs-local-authentication) +> * The external authentication provider suppports [user groups]({{}}/rancher/v2.x/en/admin-settings/authentication/user-groups/) +> * You have already set up at least one user group with the authentication provider + +To assign a custom global role to a group, follow these steps: + +1. From the **Global** view, go to **Security > Groups.** +1. Click **Assign Global Role.** +1. In the **Select Group To Add** field, choose the existing group that will be assigned the custom global role. +1. In the **Global Permissions,** **Custom,** and/or **Built-in** sections, select the permissions that the group should have. +1. Click **Create.** + +**Result:** The custom global role will take effect when the users in the group log into Rancher. + +### Refreshing Group Memberships + +When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again. + +To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships. + +An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group. + +To refresh group memberships, + +1. From the **Global** view, click **Security > Users.** +1. Click **Refresh Group Memberships.** + +**Result:** Any changes to the group members' permissions will take effect. \ No newline at end of file diff --git a/content/rancher/v2.x/en/best-practices/containers/_index.md b/content/rancher/v2.x/en/best-practices/containers/_index.md index ce67e87ef6d..410dfb2f437 100644 --- a/content/rancher/v2.x/en/best-practices/containers/_index.md +++ b/content/rancher/v2.x/en/best-practices/containers/_index.md @@ -32,11 +32,11 @@ When possible, use a non-privileged user when running processes within your cont ### Define Resource Limits Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices. -In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the [Rancher docs]({{}}/rancher/v2.x/en/project-admin/resource-quotas/). +In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs. When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace. -The Kubernetes docs have more information on how resource limits can be set at the [container level](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) and the [namespace level](https://kubernetes.io/docs/concepts/policy/resource-quotas/). +The Kubernetes docs have more information on how resource limits can be set at the [container level](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) and the namespace level. ### Define Resource Requirements You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining `resources.requests` in the resource requests field in a pod's container spec. For details, refer to the [Kubernetes docs](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container). diff --git a/content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/_index.md index ac8843d1ecb..9df03283a12 100644 --- a/content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/_index.md @@ -9,7 +9,7 @@ A Rancher [administrator]({{}}/rancher/v2.x/en/admin-settings/rbac/glob 1. From the **Global** view, navigate to the **cluster** where you want to enable Istio. 1. Click **Tools > Istio.** -1. Optional: Configure member access and [resource limits]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/resources) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio. +1. Optional: Configure member access and [resource limits]({{}}/rancher/v2.x/en/cluster-admin/tools/istio/resources/) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio. 1. Click **Enable**. 1. Click **Save**. 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 index 1313a317b15..89629d989da 100644 --- 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 @@ -63,9 +63,9 @@ The registry configuration here is applied during the provisioning of the cluste - **System images** are components needed to maintain the Kubernetes cluster. - **Add-ons** are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server. -To deploy workloads that pull images from a private registry, you will need to [set up your own Kubernetes registry]({{}}/rancher/v2.x/en/k8s-in-rancher/registries/) for your project. +To deploy workloads that pull images from a private registry, you will need to set up your own Kubernetes registry for your project. -See the [RKE documentation on private registries]({{< baseurl >}}/rke/latest/en/config-options/private-registries/) for more information on the private registry for components applied during the provisioning of the cluster. +See the RKE documentation on private registries for more information on the private registry for components applied during the provisioning of the cluster. ### Authorized Cluster Endpoint diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index cb1a30a5233..1ac1f8e34ad 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -62,20 +62,20 @@ Rancher relies on [cert-manager](https://github.com/jetstack/cert-manager) to is > **Important:** > Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher. -> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.9.1, please see our [upgrade documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). +> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). -These instructions are adapted from the [official cert-manager documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#installing-with-helm). +These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm). ``` # Install the CustomResourceDefinition resources separately -kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml +kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + +> **Important:** +> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. # Create the namespace for cert-manager kubectl create namespace cert-manager -# Label the cert-manager namespace to disable resource validation -kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - # Add the Jetstack Helm repository helm repo add jetstack https://charts.jetstack.io @@ -86,7 +86,7 @@ helm repo update helm install \ cert-manager jetstack/cert-manager \ --namespace cert-manager \ - --version v0.9.1 + --version v0.12.0 ``` Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: @@ -94,13 +94,12 @@ Once you’ve installed cert-manager, you can verify it is deployed correctly by ``` kubectl get pods --namespace cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m -cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m -cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m ``` -If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check the [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide. {{% /accordion %}} ### Install Rancher with Helm and Your Chosen Certificate Option diff --git a/content/rancher/v2.x/en/installation/options/chart-options/_index.md b/content/rancher/v2.x/en/installation/options/chart-options/_index.md index db92df57800..de2cfcde766 100644 --- a/content/rancher/v2.x/en/installation/options/chart-options/_index.md +++ b/content/rancher/v2.x/en/installation/options/chart-options/_index.md @@ -32,6 +32,8 @@ aliases: | `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated (only applies when `auditLog.destination` is set to `hostPath`) | | `busyboxImage` | "busybox" | `string` - Image location for busybox image used to collect audit logs _Note: Available as of v2.2.0_ | | `debug` | false | `bool` - set debug flag on rancher server | +| `certmanager.version` | "" | `string` - set cert-manager compatibility + | | `extraEnv` | [] | `list` - set additional environment variables for Rancher _Note: Available as of v2.2.0_ | | `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials | | `ingress.extraAnnotations` | {} | `map` - additional annotations to customize the ingress | diff --git a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md index 69ad051a38e..a28d310cfda 100644 --- a/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md +++ b/content/rancher/v2.x/en/installation/options/upgrading-cert-manager/_index.md @@ -6,7 +6,8 @@ weight: 2040 Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, two important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: 1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) -1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html#upgrading-from-v0-7-to-v0-8). This change has no exact deadline. +1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). This change has no exact deadline. +2. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/) To address these changes, this guide will do two things: @@ -20,24 +21,36 @@ To address these changes, this guide will do two things: In order to upgrade cert-manager, follow these instructions: {{% accordion id="normal" label="Upgrading cert-manager with Internet access" %}} -1. Back up existing resources as a precaution +1. [Back up existing resources](https://cert-manager.io/docs/tutorials/backup/) as a precaution ```plain - kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` -1. Delete the existing deployment +> **Important:** +> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + +1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm) ```plain helm delete --purge cert-manager ``` -1. Install the CustomResourceDefinition resources separately + Delete the CustomResourceDefinition using the link to the version vX.Y you installed ```plain - kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + kubectl delete -f https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml ``` -1. Label the kube-system namespace to disable resource validation +1. Install the CustomResourceDefinition resources separately ```plain - kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true + kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + ``` + +> **Important:** +> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + +1. Create the namespace for cert-manager if needed + ```plain + kubectl create namespace cert-manager ``` 1. Add the Jetstack Helm repository @@ -52,8 +65,17 @@ In order to upgrade cert-manager, follow these instructions: 1. Install the new version of cert-manager ```plain - helm install --version 0.9.1 --name cert-manager --namespace kube-system jetstack/cert-manager + helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --version v0.12.0 ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + {{% /accordion %}} {{% accordion id="airgap" label="Upgrading cert-manager in an airgapped environment" %}} @@ -73,23 +95,24 @@ Before you can perform the upgrade, you must prepare your air gapped environment 1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). ```plain - helm fetch jetstack/cert-manager --version v0.9.1 + helm fetch jetstack/cert-manager --version v0.12.0 ``` 1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. ```plain - helm template ./cert-manager-v0.9.1.tgz --output-dir . \ - --name cert-manager --namespace kube-system \ + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ + --name cert-manager --namespace cert-manager \ --set image.repository=/quay.io/jetstack/cert-manager-controller --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector ``` -1. Download the required CRD file for cert-manager +1. Download the required CRD file for cert-manager (old and new) ```plain - curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml ``` ### Install cert-manager @@ -97,13 +120,24 @@ Before you can perform the upgrade, you must prepare your air gapped environment 1. Back up existing resources as a precaution ```plain - kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml ``` +> **Important:** +> If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. [Additional annotation changes](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + 1. Delete the existing cert-manager installation ```plain - kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + kubectl -n cert-manager \ + delete deployment,sa,clusterrole,clusterrolebinding \ + -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + ``` + + Delete the CustomResourceDefinition using the link to the version vX.Y you installed + ```plain + kubectl delete -f cert-manager/cert-manager-crd-old.yaml ``` 1. Install the CustomResourceDefinition resources separately @@ -112,42 +146,53 @@ Before you can perform the upgrade, you must prepare your air gapped environment kubectl apply -f cert-manager/cert-manager-crd.yaml ``` -1. Label the kube-system namespace to disable resource validation +> **Important:** +> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + +1. Create the namespace for cert-manager ```plain - kubectl label namespace kube-system certmanager.k8s.io/disable-validation=true + kubectl create namespace cert-manager ``` 1. Install cert-manager ```plain - kubectl -n kube-system apply -R -f ./cert-manager + kubectl -n cert-manager apply -R -f ./cert-manager ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + {{% /accordion %}} Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods: ``` -kubectl get pods --namespace kube-system +kubectl get pods --namespace cert-manager -NAME READY STATUS RESTARTS AGE -cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m -cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m -cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m ``` -If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide. - -> **Note:** The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary: -> -> - [Information on the disable-validation label](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.4-0.5.html?highlight=certmanager.k8s.io%2Fdisable-validation#disabling-resource-validation-on-the-cert-manager-namespace) -> - [Information on webhook validation for certificates](https://docs.cert-manager.io/en/latest/getting-started/webhook.html) - ## Cert-Manager API change and data migration Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release. Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format. -Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://docs.cert-manager.io/en/latest/tasks/upgrading/upgrading-0.7-0.8.html). +Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io. + +We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the [upgrading to v0.8 guide](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/). + +More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrading/). + diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md index c4cb3081474..ac08fb75fd5 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md @@ -71,6 +71,7 @@ When setting up the Rancher Helm template, there are several options in the Helm | Chart Option | Chart Value | Description | | ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `certmanager.version` | "" | Configure proper Rancher TLS issuer depending of running cert-manager version. | | `systemDefaultRegistry` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | | `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ | @@ -81,7 +82,7 @@ Based on the choice your made in [B. Choose your SSL Configuration](#b-optional- By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. > **Note:** -> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.9.1, please see our [upgrade cert-manager documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). +> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{< baseurl >}}/rancher/v2.x/en/installation/options/upgrading-cert-manager/). 1. From a system connected to the internet, add the cert-manager repo to Helm. @@ -93,13 +94,13 @@ By default, Rancher generates a CA and uses cert-manager to issue the certificat 1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). ```plain - helm fetch jetstack/cert-manager --version v0.9.1 + helm fetch jetstack/cert-manager --version v0.12.0 ``` 1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. ```plain - helm template ./cert-manager-v0.9.1.tgz --output-dir . \ + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ --name cert-manager --namespace cert-manager \ --set image.repository=/quay.io/jetstack/cert-manager-controller --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook @@ -109,7 +110,7 @@ By default, Rancher generates a CA and uses cert-manager to issue the certificat 1. Download the required CRD file for cert-manager ```plain - curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml ``` 1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. @@ -120,12 +121,14 @@ By default, Rancher generates a CA and uses cert-manager to issue the certificat `` | The version number of the output tarball. `` | The DNS name you pointed at your load balancer. `` | The DNS name for your private registry. + `` | Cert-manager version running on k8s cluster. ```plain helm template ./rancher-.tgz --output-dir . \ --name rancher \ --namespace cattle-system \ --set hostname= \ + --set certmanager.version= \ --set rancherImage=/rancher/rancher \ --set systemDefaultRegistry= \ # Available as of v2.2.0, set a default private registry to be used in Rancher --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts @@ -182,18 +185,15 @@ If you are using self-signed certificates, install cert-manager: kubectl create namespace cert-manager ``` -1. Label the cert-manager namespace to disable resource validation. - - ```plain - kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true - ``` - 1. Create the cert-manager CustomResourceDefinitions (CRDs). ```plain kubectl apply -f cert-manager/cert-manager-crd.yaml ``` +> **Important:** +> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + 1. Launch cert-manager. ```plain kubectl apply -R -f ./cert-manager diff --git a/content/rancher/v2.x/en/installation/requirements/_index.md b/content/rancher/v2.x/en/installation/requirements/_index.md index 2d4c1010be3..82577dd86b0 100644 --- a/content/rancher/v2.x/en/installation/requirements/_index.md +++ b/content/rancher/v2.x/en/installation/requirements/_index.md @@ -161,14 +161,14 @@ TCP/UDP | 30000-32767 | Any source that consumes NodePort services | NodePort po Protocol | Port | Source | Destination | Description -----------|------|----------|---------------|-------------- TCP | 22 | RKE node | Any node configured in Cluster Configuration File | SSH provisioning of node by RKE -TCP | 443 | Rancher nodes | Rancher agent | -TCP | 2379 | etcd nodes | etcd client requests | -TCP | 2380 | etcd nodes | etcd peer communication | +TCP | 443 | Rancher nodes | Rancher agent | +TCP | 2379 | etcd nodes | etcd client requests | +TCP | 2380 | etcd nodes | etcd peer communication | TCP | 6443 | RKE node | controlplane nodes | Kubernetes API server -TCP | 6443 | controlplane nodes | Kubernetes API server | -UDP | 8472 | etcd nodes, controlplane nodes, and worker nodes | Canal/Flannel VXLAN overlay networking | -TCP | 9099 | the node itself (local traffic, not across nodes) | Canal/Flannel livenessProbe/readinessProbe | -TCP | 10250 | etcd nodes, controlplane nodes, and worker nodes | kubelet | +TCP | 6443 | controlplane nodes | Kubernetes API server | +UDP | 8472 | etcd nodes, controlplane nodes, and worker nodes | Canal/Flannel VXLAN overlay networking | +TCP | 9099 | the node itself (local traffic, not across nodes) | Canal/Flannel livenessProbe/readinessProbe | +TCP | 10250 | etcd nodes, controlplane nodes, and worker nodes | kubelet | TCP | 10254 | the node itself (local traffic, not across nodes) | Ingress controller livenessProbe/readinessProbe The ports that need to be opened for each node depend on the node's Kubernetes role: etcd, controlplane, or worker. If you installed Rancher on a Kubernetes cluster that doesn't have all three roles on each node, refer to the [port requirements for the Rancher Kubernetes Engine (RKE).]({{}}/rke/latest/en/os/#ports) The RKE docs show a breakdown of the port requirements for each role. @@ -188,6 +188,9 @@ The following diagram depicts the ports that are opened for each [cluster type]( The following tables break down the port requirements for inbound and outbound traffic: +**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example). + +
Inbound Rules for Rancher Nodes
| Protocol | Port | Source | Description | @@ -195,6 +198,7 @@ The following tables break down the port requirements for inbound and outbound t | TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used | | TCP | 443 |
  • etcd nodes
  • controlplane nodes
  • worker nodes
  • hosted/imported Kubernetes
  • any source that needs to be able to use the Rancher UI or API
| Rancher agent, Rancher UI/API, kubectl | +
Outbound Rules for Rancher Nodes
| Protocol | Port | Source | Description | diff --git a/content/rancher/v2.x/en/installation/requirements/ports/_index.md b/content/rancher/v2.x/en/installation/requirements/ports/_index.md index 5c79484b9e1..a39ef0ca510 100644 --- a/content/rancher/v2.x/en/installation/requirements/ports/_index.md +++ b/content/rancher/v2.x/en/installation/requirements/ports/_index.md @@ -11,7 +11,7 @@ The following table lists the ports that need to be open to and from nodes that {{< ports-rancher-nodes >}} -**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example). +**Note** Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example). ## Kubernetes Cluster Nodes diff --git a/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md b/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md index daaa5b1427b..f8f82c6aab1 100644 --- a/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md @@ -40,7 +40,7 @@ For information on other default alerts, refer to the section on [cluster-level ## Adding Project Alerts ->**Prerequisite:** Before you can receive project alerts, you must [add a notifier]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/notifiers/#adding-notifiers). +>**Prerequisite:** Before you can receive project alerts, you must add a notifier. 1. From the **Global** view, navigate to the project that you want to configure project alerts for. Select **Tools > Alerts**. In versions prior to v2.2.0, you can choose **Resources > Alerts**. diff --git a/content/rancher/v2.x/en/security/_index.md b/content/rancher/v2.x/en/security/_index.md index 913927b32ed..2ee41833ca0 100644 --- a/content/rancher/v2.x/en/security/_index.md +++ b/content/rancher/v2.x/en/security/_index.md @@ -20,15 +20,38 @@ weight: 7505 +Security is at the heart of all Rancher features. From integrating with all the popular authentication tools and services, to an enterprise grade [RBAC capability,]({{}}/rancher/v2.x/en/admin-settings/rbac) Rancher makes your Kubernetes clusters even more secure. + +On this page, we provide security-related documentation along with resources to help you secure your Rancher installation and your downstream Kubernetes clusters: + +- [Running a CIS security scan on a Kubernetes cluster](#running-a-cis-security-scan-on-a-kubernetes-cluster) +- [Guide to hardening Rancher installations](#rancher-hardening-guide) +- [The CIS Benchmark and self-assessment](#the-cis-benchmark-and-self-assessment) +- [Third-party penetration test reports](#third-party-penetration-test-reports) +- [Rancher CVEs and resolutions](#rancher-cves-and-resolutions) +- [Security Tips and Best Practices](#security-tips-and-best-practices) + +### Running a CIS Security Scan on a Kubernetes Cluster + +_Available as of v2.4_ + +Rancher leverages [kube-bench](https://github.com/aquasecurity/kube-bench) to run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS (Center for Internet Security) Kubernetes Benchmark. + +The CIS Kubernetes Benchmark is a reference document that can be used to establish a secure configuration baseline for Kubernetes. The Benchmark provides recommendations of two types: Scored and Not Scored. We run tests related to only Scored recommendations. + +When Rancher runs a CIS Security Scan on a cluster, it generates a report showing the results of each test, including a summary with the number of passed, skipped and failed tests. The report also includes remediation steps for any failed tests. + +For details, refer to the section on [security scans.]({{}}/rancher/v2.x/en/security/security-scan) + ### Rancher Hardening Guide -The Rancher Hardening Guide is based off of controls and best practices found in the [CIS Kubernetes Benchmark](https://www.cisecurity.org/benchmark/kubernetes/) from the Center for Internet Security. The hardening guide provides prescriptive guidance for hardening a production installation of Rancher v2.1.x, v2.2.x and v.2.3.x. See Rancher's [Self Assessment of the CIS Kubernetes Benchmark](#cis-benchmark-rancher-self-assessment) for the full list of security controls. +The Rancher Hardening Guide is based off of controls and best practices found in the CIS Kubernetes Benchmark from the Center for Internet Security. The hardening guide provides prescriptive guidance for hardening a production installation of Rancher v2.1.x, v2.2.x and v.2.3.x. See Rancher's [Self Assessment of the CIS Kubernetes Benchmark](#cis-benchmark-rancher-self-assessment) for the full list of security controls. - [Hardening Guide for Rancher v2.1.x with Kubernetes 1.11]({{< baseurl >}}/rancher/v2.x/en/security/hardening-2.1/) - [Hardening Guide for Rancher v2.2.x with Kubernetes 1.13]({{< baseurl >}}/rancher/v2.x/en/security/hardening-2.2/) - [Hardening Guide for Rancher v2.3.x with Kubernetes 1.15]({{< baseurl >}}/rancher/v2.x/en/security/hardening-2.3/) -### CIS Benchmark Rancher Self-Assessment +### The CIS Benchmark and Self-Assessment The benchmark self-assessment is a companion to the Rancher security hardening guide. While the hardening guide shows you how to harden the cluster, the benchmark guide is meant to help you evaluate the level of security of the hardened cluster. @@ -39,7 +62,7 @@ Because Rancher and RKE install Kubernetes services as Docker containers, many o - [CIS Kubernetes Benchmark 1.4.1 - Rancher 2.2.x with Kubernetes 1.13]({{< baseurl >}}/rancher/v2.x/en/security/benchmark-2.2/#cis-kubernetes-benchmark-1-4-1-rancher-2-2-x-with-kubernetes-1-13) - [CIS Kubernetes Benchmark 1.4.1 - Rancher 2.3.x with Kubernetes 1.15]({{< baseurl >}}/rancher/v2.x/en/security/benchmark-2.3/#cis-kubernetes-benchmark-1-4-1-rancher-2-3-x-with-kubernetes-1-15) -### Third Party Pen Test Reports +### Third-party Penetration Test Reports Rancher periodically hires third parties to perform security audits and penetration tests of the Rancher 2.x software stack. The environments under test follow the Rancher provided hardening guides at the time of the testing. Results are posted when the third party has also verified fixes classified MEDIUM or above. @@ -62,3 +85,7 @@ Rancher is committed to informing the community of security issues in our produc | [CVE-2019-13209](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-13209) | The vulnerability is known as a [Cross-Site Websocket Hijacking attack](https://www.christian-schneider.net/CrossSiteWebSocketHijacking.html). This attack allows an exploiter to gain access to clusters managed by Rancher with the roles/permissions of a victim. It requires that a victim to be logged into a Rancher server and then access a third-party site hosted by the exploiter. Once that is accomplished, the exploiter is able to execute commands against the Kubernetes API with the permissions and identity of the victim. Reported by Matt Belisle and Alex Stevenson from Workiva. | 15 Jul 2019 | [Rancher v2.2.5](https://github.com/rancher/rancher/releases/tag/v2.2.5), [Rancher v2.1.11](https://github.com/rancher/rancher/releases/tag/v2.1.11) and [Rancher v2.0.16](https://github.com/rancher/rancher/releases/tag/v2.0.16) | | [CVE-2019-14436](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-14436) | The vulnerability allows a member of a project that has access to edit role bindings to be able to assign themselves or others a cluster level role granting them administrator access to that cluster. The issue was found and reported by Michal Lipinski at Nokia. | 5 Aug 2019 | [Rancher v2.2.7](https://github.com/rancher/rancher/releases/tag/v2.2.7) and [Rancher v2.1.12](https://github.com/rancher/rancher/releases/tag/v2.1.12) | | [CVE-2019-14435](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-14435) | This vulnerability allows authenticated users to potentially extract otherwise private data out of IPs reachable from system service containers used by Rancher. This can include but not only limited to services such as cloud provider metadata services. Although Rancher allow users to configure whitelisted domains for system service access, this flaw can still be exploited by a carefully crafted HTTP request. The issue was found and reported by Matt Belisle and Alex Stevenson at Workiva. | 5 Aug 2019 | [Rancher v2.2.7](https://github.com/rancher/rancher/releases/tag/v2.2.7) and [Rancher v2.1.12](https://github.com/rancher/rancher/releases/tag/v2.1.12) | + +### Security Tips and Best Practices + +Our [best practices guide]({{}}/rancher/v2.x/en/best-practices/management/#tips-for-security) includes basic tips for increasing security in Rancher. \ No newline at end of file diff --git a/content/rancher/v2.x/en/security/security-scan/_index.md b/content/rancher/v2.x/en/security/security-scan/_index.md new file mode 100644 index 00000000000..6af630675d9 --- /dev/null +++ b/content/rancher/v2.x/en/security/security-scan/_index.md @@ -0,0 +1,66 @@ +--- +title: Security Scans +weight: 1 +--- + +_Available as of v2.4_ + +Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS (Center for Internet Security) Kubernetes Benchmark. + +The CIS Kubernetes Benchmark is a reference document that can be used to establish a secure configuration baseline for Kubernetes. The Benchmark provides recommendations of two types: Scored and Not Scored. We run tests related to only Scored recommendations. + +When Rancher runs a CIS Security Scan on a cluster, it generates a report showing the results of each test, including a summary with the number of passed, skipped and failed tests. The report also includes remediation steps for any failed tests. + +To check clusters for CIS Kubernetes Benchmark compliance, the security scan leverages [kube-bench,](https://github.com/aquasecurity/kube-bench) an open-source tool from Aqua Security. + +### About the Generated Report + +Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format. + +To determine which version of the [Benchmark](https://www.cisecurity.org/benchmark/kubernetes/) to use in the scan, Rancher chooses a version that is appropriate for the cluster's Kubernetes version. The Benchmark version is included in the generated report. + +Each test in the report is identified by its corresponding Scored test in the Benchmark. For example, if a cluster fails test 1.3.6, you can look up the description and rationale for the section 1.3.6 in the Benchmark itself, or in Rancher's [hardening guide for the Kubernetes version that the cluster is using.]({{}}/rancher/v2.x/en/security/#rancher-hardening-guide) Recommendations marked as Not Scored in the Benchmark are not included in the report. + +Similarly, for information on how to manually audit the test result, you could look up section 1.3.6 in Rancher's [self-assessment guide for the corresponding Kubernetes version.]({{}}/rancher/v2.x/en/security/#the-cis-benchmark-and-self-assessment) + +### Prerequisites + +To run security scans on a cluster and access the generated reports, you must be an [Administrator]({{}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) or [Cluster Owner.]({{}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) + +Rancher can only run security scans on clusters that were created with RKE, which includes custom clusters and clusters that Rancher created in an infrastructure provider such as Amazon EC2 or GCE. Imported clusters and clusters in hosted Kubernetes providers can't be scanned by Rancher. + +The security scan cannot run in a cluster that has Windows nodes. + +### Running a Scan + +1. From the cluster view in Rancher, click **Tools > CIS Scans.** +1. Click **Run Scan.** + +**Result:** A report is generated and displayed in the **CIS Scans** page. To see details of the report, click the report's name. + +### Skipping a Test + +1. From the cluster view in Rancher, click **Tools > CIS Scans.** +1. Click the name of the report that has tests you want to skip. +1. A **Skip** button is displayed next to each failed test. Click **Skip** for each test that should be skipped. + +**Result:** The tests will be skipped on the next scan. + +To re-run the security scan, go to the top of the page and click **Run Scan.** + +### Un-skipping a Test + +1. From the cluster view in Rancher, click **Tools > CIS Scans.** +1. Click the name of the report that has tests you want to un-skip. +1. An **Unskip** button is displayed next to each skipped test. Click **Unskip** for each test that should not be skipped. + +**Result:** The tests will not be skipped on the next scan. + +To re-run the security scan, go to the top of the page and click **Run Scan.** + +### Deleting a Report + +1. From the cluster view in Rancher, click **Tools > CIS Scans.** +1. Go to the report that should be deleted. +1. Click the **Ellipsis (...) > Delete.** +1. Click **Delete.** \ No newline at end of file diff --git a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md index fc26a3018f5..864a5b88eb7 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha/_index.md @@ -109,6 +109,7 @@ This section describes how to upgrade normal (Internet-connected) or air gap ins `` | The version number of the output tarball. `` | The DNS name you pointed at your load balancer. `` | The DNS name for your private registry. + `` | Cert-manager version running on k8s cluster. {{% accordion id="self-signed" label="Option A-Default Self-Signed Certificate" %}} @@ -117,6 +118,7 @@ helm template ./rancher-.tgz --output-dir . \ --name rancher \ --namespace cattle-system \ --set hostname= \ + --set certmanager.version= \ --set rancherImage=/rancher/rancher \ --set systemDefaultRegistry= \ # Available as of v2.2.0, set a default private registry to be used in Rancher --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts