mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-24 20:18:18 +00:00
updating rbac and catalogs
This commit is contained in:
Denise Schannon
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Authentication
|
||||
weight: 50
|
||||
weight: 1110
|
||||
aliases:
|
||||
-/rancher/v2.x/en/concepts/global-configuration/authentication/
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
6. The external principal and the local principal share the same access rights.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring Active Directory (AD)
|
||||
weight: 50
|
||||
weight: 1112
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/active-directory/
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring Azure AD
|
||||
weight: 75
|
||||
weight: 1115
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/azure-ad/
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring FreeIPA
|
||||
weight: 150
|
||||
weight: 1114
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/freeipa/
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring GitHub
|
||||
weight: 100
|
||||
weight: 1116
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/github/
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring Local Authentication
|
||||
weight: 25
|
||||
weight: 1111
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/local-authentication/
|
||||
---
|
||||
@@ -9,4 +9,4 @@ Regardless of whether you use external authentication, you should create a few l
|
||||
|
||||
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.
|
||||
2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring OpenLDAP
|
||||
weight: 125
|
||||
weight: 1113
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/authentication/openLDAP/
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: RBAC
|
||||
weight: 75
|
||||
title: Roles in Rancher
|
||||
weight: 1125
|
||||
aliases:
|
||||
-/rancher/v2.x/en/admin-settings/rbac/
|
||||
---
|
||||
@@ -17,182 +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.
|
||||
|
||||
@@ -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.
|
||||
+6
-22
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Creating Roles
|
||||
weight: 25
|
||||
title: Custom Roles
|
||||
weight: 1128
|
||||
aliases:
|
||||
-/rancher/v2.x/en/tasks/global-configuration/roles/
|
||||
---
|
||||
@@ -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**.
|
||||
@@ -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`.
|
||||
@@ -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**.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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
|
||||
|
||||
@@ -4,14 +4,11 @@ weight: 4000
|
||||
aliases:
|
||||
- /rancher/v2.x/en/concepts/global-configuration/catalog/
|
||||
- /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/
|
||||
---
|
||||
|
||||
This section includes step-by-step instruction on how to configure default and custom catalogs.
|
||||
|
||||
- [Enabling Default Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/enabling-default-catalog/)
|
||||
- [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-catalogs/)
|
||||
- [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-charts/)
|
||||
|
||||
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_.
|
||||
|
||||
@@ -21,148 +18,79 @@ _Charts_ are a packaging format popularized by [Helm](https://docs.helm.sh/). Th
|
||||
|
||||
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
|
||||
## Enabling Built-in Catalogs
|
||||
|
||||
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.
|
||||
Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.
|
||||
|
||||
- **Library**
|
||||
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 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.
|
||||
- **Library**
|
||||
|
||||
This catalog features Rancher Charts, which include some [notable advantages](#chart-types) over native Helm charts.
|
||||
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.
|
||||
|
||||
- **Helm Stable**
|
||||
This catalog features Rancher Charts, which include some [notable advantages](#chart-types) over native Helm charts.
|
||||
|
||||
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 Stable**
|
||||
|
||||
- **Helm Incubator**
|
||||
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.
|
||||
|
||||
Similar in user experience to Helm Stable, but this catalog is filled with applications in BETA.
|
||||
- **Helm Incubator**
|
||||
|
||||
- **Custom**
|
||||
Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
### Custom Catalog Creation
|
||||
## Adding Custom Catalogs
|
||||
|
||||
Creating a custom catalog for Rancher is straightforward. Create a Git repo and then direct Rancher toward the repo.
|
||||
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.
|
||||
|
||||
Custom catalog requirements include:
|
||||
>**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.
|
||||
<br/>
|
||||
<br/>
|
||||
|
||||
- A unique name.
|
||||
- A URL that `git clone` can handle.
|
||||
<!--There are two types of catalogs that can be added into Rancher. There are global catalogs and project catalogs. In a global catalog, the catalog templates are available in *all* projects. In a project catalog, the catalog charts are only available in the project that the catalog is added to.
|
||||
|
||||
For step-by-step directions, see [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-catalogs/).
|
||||
An [admin]({{< baseurl >}}/rancher/v2.x/en/admin-settings/#global-Permissions) of Rancher has the ability to add or remove catalogs globally in Rancher.
|
||||
|
||||
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).
|
||||
NEEDS TO BE FIXED FOR 2.0: Any [users]({{site.baseurl}}/rancher/{{page.version}}/{{page.lang}}/configuration/accounts/#account-types) of a Rancher environment has the ability to add or remove environment catalogs in their respective Rancher environment in **Catalog** -> **Manage**.
|
||||
-->
|
||||
|
||||
## Chart Types
|
||||
1. From the **Global** view, choose **Catalogs** from the main menu.
|
||||
2. Click **Add Catalog**.
|
||||
3. Complete the form and click **Create**.
|
||||
|
||||
Rancher supports two different types of charts:
|
||||
**Result**: Your catalog is added to Rancher.
|
||||
|
||||
- **Helm Charts**
|
||||
## Launching Catalog Applications
|
||||
|
||||
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.
|
||||
After you've either enabled the built-in catalogs or added your own custom catalog, you can start launching any catalog application.
|
||||
|
||||
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).
|
||||
1. From the **Global** view, open the project that you want to deploy to.
|
||||
|
||||
- **Rancher Charts**
|
||||
2. From the main menu, choose **Catalog Apps**. Then click **Launch**.
|
||||
|
||||
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).
|
||||
3. Find the app that you want to launch, and then click **View Now**.
|
||||
|
||||
Advantages of Rancher charts include:
|
||||
4. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application.
|
||||
|
||||
- **Enhanced Revision Tracking**
|
||||
* 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.
|
||||
|
||||
While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart.
|
||||
5. Select a **Template Version**.
|
||||
|
||||
- **Streamlined Application Launch**
|
||||
6. Complete the rest of the **Configuration Options**.
|
||||
|
||||
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.
|
||||
* 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**.
|
||||
|
||||
- **Application Resource Management**
|
||||
7. Review the files in **Preview**. When you're satisfied, click **Launch**.
|
||||
|
||||
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.
|
||||
**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's:
|
||||
|
||||
### 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.
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Sub-Directory </td>
|
||||
<td>File</td>
|
||||
<td>Description</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td> <code>app-readme.md</code></td>
|
||||
<td> <strong>Rancher Specific:</strong> Text displayed in the charts header within the Rancher UI.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>charts/</code></td>
|
||||
<td></td>
|
||||
<td>Directory containing dependency charts.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>Chart.yml</code></td>
|
||||
<td>Required Helm chart information file.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>questions.yml</code></td>
|
||||
<td><strong>Rancher Specific:</strong> File containing form questions displayed within the Rancher UI. Questions display in <strong>Configuration Options</strong>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>README.md</code></td>
|
||||
<td>Optional: Helm Readme file displayed within Rancher UI. This test displays in <strong>Detailed Descriptions</strong>.</td>
|
||||
</tr>
|
||||
<td></td>
|
||||
<td><code>requirements.yml</code></td>
|
||||
<td>Optional YAML file listing dependencies for the chart.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>templates/</code></td>
|
||||
<td></td>
|
||||
<td>A directory of templates that, when combined with <code>values.yml</code>, generates Kubernetes YAML.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>values.yml</code></td>
|
||||
<td>The default configuration values for the chart.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### 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).
|
||||
|
||||
<small>Rancher Chart with <code>app-readme.md</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
- `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).
|
||||
|
||||
|
||||
<small>Rancher Chart with <code>question.yml</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
|
||||
### 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/custom-charts/).
|
||||
|
||||
>**Note:** For a complete walkthrough of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/).
|
||||
- **Workloads** view
|
||||
- **Catalog Apps** view
|
||||
|
||||
@@ -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.
|
||||
<br/>
|
||||
<br/>
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- Recommended: Read [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/catalog/).
|
||||
>- 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/custom-charts/).
|
||||
@@ -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/catalog).
|
||||
>- Create a GitHub repository to serve as your custom catalog.
|
||||
>- Complete [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/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/catalog/#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.
|
||||
<br/>
|
||||
<br/>
|
||||
**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.
|
||||
<br/>
|
||||
<br/>
|
||||
The example below creates a form that prompts users for persistent volume size and a storage class.
|
||||
<br/>
|
||||
<br/>
|
||||
For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](#question-variable-reference).
|
||||
|
||||
<pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4">
|
||||
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
|
||||
</pre>
|
||||
|
||||
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/catalog/launching-catalog-apps/).
|
||||
|
||||
## 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:<br> - "ClusterIP" <br> - "NodePort" <br> - "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.
|
||||
@@ -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.
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Sub-Directory </td>
|
||||
<td>File</td>
|
||||
<td>Description</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td> <code>app-readme.md</code></td>
|
||||
<td> <strong>Rancher Specific:</strong> Text displayed in the charts header within the Rancher UI.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>charts/</code></td>
|
||||
<td></td>
|
||||
<td>Directory containing dependency charts.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>Chart.yml</code></td>
|
||||
<td>Required Helm chart information file.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>questions.yml</code></td>
|
||||
<td><strong>Rancher Specific:</strong> File containing form questions displayed within the Rancher UI. Questions display in <strong>Configuration Options</strong>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>README.md</code></td>
|
||||
<td>Optional: Helm Readme file displayed within Rancher UI. This test displays in <strong>Detailed Descriptions</strong>.</td>
|
||||
</tr>
|
||||
<td></td>
|
||||
<td><code>requirements.yml</code></td>
|
||||
<td>Optional YAML file listing dependencies for the chart.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>templates/</code></td>
|
||||
<td></td>
|
||||
<td>A directory of templates that, when combined with <code>values.yml</code>, generates Kubernetes YAML.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td><code>values.yml</code></td>
|
||||
<td>The default configuration values for the chart.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## 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).
|
||||
|
||||
<small>Rancher Chart with <code>app-readme.md</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
- `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).
|
||||
|
||||
|
||||
<small>Rancher Chart with <code>question.yml</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
|
||||
### 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:<br> - "ClusterIP" <br> - "NodePort" <br> - "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.
|
||||
<br/>
|
||||
<br/>
|
||||
**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.
|
||||
<br/>
|
||||
<br/>
|
||||
The example below creates a form that prompts users for persistent volume size and a storage class.
|
||||
<br/>
|
||||
<br/>
|
||||
For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](#question-variable-reference).
|
||||
|
||||
<pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4">
|
||||
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
|
||||
</pre>
|
||||
|
||||
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.
|
||||
@@ -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/catalog/#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/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/catalog/launching-catalog-apps).
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Launching Catalog Applications
|
||||
weight: 4010
|
||||
---
|
||||
|
||||
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/catalog/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
|
||||
@@ -42,7 +42,7 @@ Following cluster creation, you can add users as cluster members so that they ca
|
||||
|
||||
4. Assign the user or group **Cluster** roles.
|
||||
|
||||
[What are Cluster Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#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.
|
||||
>
|
||||
|
||||
@@ -18,8 +18,8 @@ For more information on creating node drivers, see [https://github.com/rancher/u
|
||||
|
||||
>**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/#custom-global-permissions) with the [Manage Node Drivers]({{< 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 Node Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
|
||||
|
||||
## Adding Custom Node Drivers
|
||||
|
||||
|
||||
+8
-3
@@ -12,10 +12,15 @@ aliases:
|
||||
|
||||
1. Enter a **Project Name**.
|
||||
|
||||
1. **Optional:** Select a **Pod Security Policy**.
|
||||
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.
|
||||
|
||||
[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.
|
||||
@@ -32,9 +37,9 @@ aliases:
|
||||
|
||||
1. From the **Role** drop-down, choose a role.
|
||||
|
||||
[What are Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#cluster-and-project-roles)
|
||||
[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/#custom-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
-1
@@ -39,7 +39,7 @@ Following project creation, you can add users as project members so that they ca
|
||||
|
||||
1. Assign the user or group **Project** roles.
|
||||
|
||||
[What are Project Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#cluster-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.
|
||||
>
|
||||
|
||||
+1
-1
@@ -7,7 +7,7 @@ aliases:
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- Working with storage requires the `Manage Volumes` [role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/#project-role-reference).
|
||||
>- 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](provisioning-storage).
|
||||
|
||||
## Adding a Persistent Volume
|
||||
|
||||
Reference in New Issue
Block a user