mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 13:08:11 +00:00
Merge release v2.13.0 to main (#2091)
* Sync main to v2.13.0 (#2065) * It's bad form to ask users to pass something they just curled from the internet directly to sh Updated the instructions for uninstalling the rancher-system-agent to use a temporary script file instead of piping directly to sh. * doc(rancher-security): improve structure and content to latest, v2.13-preview and v2.12 (#2024) - add Rancher Kubernetes Distributions (K3s/RKE2) Self-Assessment and Hardening Guide section - add kubernetes cluster security best practices link to rancher-security section - add k3s-selinux and update selinux-rpm details - remove rhel/centos 7 support Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> * Updating across supported versions and translations. Signed-off-by: Sunil Singh <sunil.singh@suse.com> --------- Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> Signed-off-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Tejeev <tj@rancher.com> Co-authored-by: Andy Pitcher <andy.pitcher@suse.com> Co-authored-by: Sunil Singh <sunil.singh@suse.com> * Update roletemplate aggregation doc and version information * Add versioned docs * Remove ext token and kubeconfig feature flag sections and document bearer Token * Update corresponding v2.13 pages * update doc for pni in gke * Adding reverted session idle information from PR 1653 Signed-off-by: Sunil Singh <sunil.singh@suse.com> * [2.13.0] Add versions table entry * [2.13.0] Add webhook version * [2.13.0] Add CSP Adapter version * [2.13.0] Add deprecated feature table entry * [2.13.0] Update CNI popularity stats * Update GKE Cluster Configuration for Project Network Isolation instructions * Fix link and port to 2.13 * [2.13.0] Add Swagger JSON * [v2.13.0] Add info about Azure AD Roles claims (#2079) * Add info about Azure AD roles claims compatibility * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> * Add suggestions to v2.13 --------- Co-authored-by: Sunil Singh <sunil.singh@suse.com> * [2.13.0] Remove preview designation * user public api docs (#2069) * user public api docs * Apply suggestions from code review Co-authored-by: Andreas Kupries <akupries@suse.com> * Apply suggestions from code review Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> * explain plaintext is never stored * add users 2.13 versioned docs * remove extra ``` * Apply suggestions from code review Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> * add space before code block --------- Co-authored-by: Andreas Kupries <akupries@suse.com> Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> * support IPv6 (#2041) * [v2.13.0] Add Configure GitHub App page (#2081) * Add Configure GitHub App page * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> * Fix header/GH URL & add suggestions to v2.13 * Apply suggestions from code review Co-authored-by: Petr Kovar <pknbe@volny.cz> * Apply suggestions from code review to v2.13 * Add note describing why to use Installation ID * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> --------- Co-authored-by: Billy Tat <btat@suse.com> Co-authored-by: Petr Kovar <pknbe@volny.cz> * [v2.13.0] Add info about Generic OIDC Custom Mapping (#2080) * Add info about Generic OIDC Custom Mapping * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * Apply suggestions from code review Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * Add suggestions to v2.13 * Remove repetitive statement in intro * Move Prereq intro/note to appropriate section * Fix formatting, UI typo, add Custom Claims section under Configuration Reference section * Add section about how a custom groups claim works / note about search limitations for groups in RBAC --------- Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Billy Tat <btat@suse.com> * [v2.13.0] Add info about OIDC SLO support (#2086) * Add shared file covering OIDC SLO support to OIDC auth pages * Ad How to get the End Session Endpoint steps * Add generic curl exampleto retrieve end_session_endpoint * [2.13.0] Bump release date --------- Signed-off-by: Andy Pitcher <andy.pitcher@suse.com> Signed-off-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> Co-authored-by: Tejeev <tj@rancher.com> Co-authored-by: Andy Pitcher <andy.pitcher@suse.com> Co-authored-by: Sunil Singh <sunil.singh@suse.com> Co-authored-by: Jonathan Crowther <jonathan.crowther@suse.com> Co-authored-by: Peter Matseykanets <peter.matseykanets@suse.com> Co-authored-by: Petr Kovar <petr.kovar@suse.com> Co-authored-by: Krunal Hingu <krunal.hingu222@gmail.com> Co-authored-by: Raul Cabello Martin <raul.cabello@suse.com> Co-authored-by: Andreas Kupries <akupries@suse.com> Co-authored-by: Peter Matseykanets <pmatseykanets@gmail.com> Co-authored-by: Jack Luo <jiaqi.luo@suse.com> Co-authored-by: Petr Kovar <pknbe@volny.cz>
This commit is contained in:
Billy Tat
co-authored by
Tejeev
Andy Pitcher
Sunil Singh
Andreas Kupries
Peter Matseykanets
Lucas Saintarbor
Petr Kovar
Jonathan Crowther
Peter Matseykanets
Petr Kovar
Krunal Hingu
Raul Cabello Martin
Jack Luo
Tejeev
Andy Pitcher
Sunil Singh
Andreas Kupries
Peter Matseykanets
Lucas Saintarbor
Petr Kovar
Jonathan Crowther
Peter Matseykanets
Petr Kovar
Krunal Hingu
Raul Cabello Martin
Jack Luo
parent
94197793cb
commit
24fc5a657c
-19
@@ -1,19 +0,0 @@
|
||||
---
|
||||
title: ClusterRole Aggregation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/cluster-role-aggregation"/>
|
||||
</head>
|
||||
|
||||
:::caution
|
||||
ClusterRole aggregation is a highly experimental feature that changes the RBAC architecture used for RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings. **It is not supported for production environments**. This feature is meant exclusively for internal testing in v2.11 and v2.12. It is expected to be available as a beta for users in v2.13.
|
||||
:::
|
||||
|
||||
ClusterRole aggregation implements RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings using the Kubernetes feature [Aggregated ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). The new architecture results in a net reduction in RBAC objects (Roles, RoleBindings, ClusterRoles and ClusterRoleBindings) both in the Rancher cluster and the downstream clusters.
|
||||
|
||||
| Environment Variable Key | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `aggregated-roletemplates` | `false` | [Experimental] Make RoleTemplates use aggregation for generated RBAC roles. |
|
||||
|
||||
The value of this feature flag is locked on installation, which shows up in the UI as a lock symbol beside the feature flag. That means the feature can only be set on the first ever installation of Rancher. After that, attempting to modify the value will be denied.
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: RoleTemplate Aggregation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation"/>
|
||||
</head>
|
||||
|
||||
:::caution
|
||||
RoleTemplate aggregation is an experimental feature in v2.13 that changes the RBAC architecture used for RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings. **It is not supported for production environments**. Breaking changes may occur between v2.13 and v2.14.
|
||||
:::
|
||||
|
||||
RoleTemplate aggregation implements RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings using the Kubernetes feature [Aggregated ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). The new architecture results in a net reduction in RBAC objects (Roles, RoleBindings, ClusterRoles and ClusterRoleBindings) both in the Rancher cluster and the downstream clusters.
|
||||
|
||||
For more information on how the feature can improve scalability and performance, please see the [Rancher Blog post](https://www.suse.com/c/rancher_blog/fewer-bindings-more-power-ranchers-rbac-boost-for-enhanced-performance-and-scalability/).
|
||||
|
||||
| Environment Variable Key | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `aggregated-roletemplates` | `false` | [Beta] Make RoleTemplates use aggregation for generated RBAC roles. |
|
||||
|
||||
The value of this feature flag is locked on installation, which shows up in the UI as a lock symbol beside the feature flag. That means the feature can only be set on the first ever installation of Rancher. After that, attempting to modify the value will be denied.
|
||||
+4
@@ -58,3 +58,7 @@ if the user has not yet logged in to Rancher. However, if the user has previousl
|
||||
### You are not redirected to your authentication provider
|
||||
|
||||
If you fill out the **Configure an Amazon Cognito account** form and click on **Enable**, and you are not redirected to Amazon Cognito, verify your Amazon Cognito configuration.
|
||||
|
||||
## Configuring OIDC Single Logout (SLO)
|
||||
|
||||
<ConfigureSLOOidc />
|
||||
+19
@@ -363,3 +363,22 @@ Since the filter prevents Rancher from seeing that the user belongs to an exclud
|
||||
>- If you don't wish to upgrade to v2.7.0+ after the Azure AD Graph API is retired, you'll need to either:
|
||||
- Use the built-in Rancher auth or
|
||||
- Use another third-party auth system and set that up in Rancher. Please see the [authentication docs](authentication-config.md) to learn how to configure other open authentication providers.
|
||||
|
||||
## Azure AD Roles Claims
|
||||
|
||||
Rancher supports the Roles claim provided by the Azure AD OIDC provider token, allowing for complete delegation of Role-Based Access Control (RBAC) to Azure AD. Previously, Rancher only processed the `Groups` claim to determine a user's `group` membership. This enhancement extends the logic to also include the Roles claim within the user's OIDC token.
|
||||
|
||||
By including the Roles claim, administrators can:
|
||||
|
||||
- Define specific high-level roles in Azure AD.
|
||||
- Bind these Azure AD Roles directly to ProjectRoles or ClusterRoles within Rancher.
|
||||
- Centralize and fully delegate access control decisions to the external OIDC provider.
|
||||
|
||||
For example, consider the following role structure in Azure AD:
|
||||
|
||||
| Azure AD Role Name | Members |
|
||||
|--------------------|----------------|
|
||||
| project-alpha-dev | User A, User C |
|
||||
|
||||
|
||||
User A logs into Rancher via Azure AD. The OIDC token includes a Roles claim, [`project-alpha-dev`]. The Rancher logic processes the token, and the internal list of `groups`/roles for User A which includes `project-alpha-dev`. An administrator has created a Project Role Binding that maps the Azure AD Role `project-alpha-dev` to the Project Role `Dev Member` for Project Alpha. User A is automatically granted the `Dev Member` role in Project Alpha.
|
||||
|
||||
+83
-37
@@ -7,60 +7,69 @@ description: Create an OpenID Connect (OIDC) client and configure Rancher to wor
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc"/>
|
||||
</head>
|
||||
|
||||
If your organization uses an OIDC provider for user authentication, you can configure Rancher to allow login using Identity Provider (IdP) credentials. Rancher supports integration with the OpenID Connect (OIDC) protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. The following instructions describe how to configure Rancher to work using the OIDC protocol.
|
||||
Generic OpenID Connect (OIDC) allows users to sign in to Rancher using their credentials from their existing account at an OIDC Identity Provider (IdP). Rancher supports integration with the OIDC protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. The following instructions describe how to create an OIDC client and configure Rancher to work with your authentication provider. Users can then sign into Rancher using their login from the OIDC IdP.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- In Rancher:
|
||||
- Generic OIDC is disabled.
|
||||
### Identity Provider
|
||||
|
||||
In Rancher, Generic OIDC is disabled.
|
||||
|
||||
:::note
|
||||
|
||||
Consult the documentation for your specific IdP to complete the listed prerequisites.
|
||||
|
||||
:::
|
||||
|
||||
- In your IdP:
|
||||
- Create a new client with the settings below:
|
||||
#### OIDC Client
|
||||
|
||||
In your IdP, create a new client with the settings below:
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Client ID` | <CLIENT_ID> (e.g. `rancher`)
|
||||
`Name` | <CLIENT_NAME> (e.g. `rancher`)
|
||||
`Client Protocol` | `openid-connect`
|
||||
`Access Type` | `confidential`
|
||||
`Valid Redirect URI` | `https://yourRancherHostURL/verify-auth`
|
||||
|
||||
In the new OIDC client, create mappers to expose the user's fields.
|
||||
|
||||
1. Create a new `Groups Mapper` with the settings below:
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Client ID` | <CLIENT_ID> (e.g. `rancher`)
|
||||
`Name` | <CLIENT_NAME> (e.g. `rancher`)
|
||||
`Client Protocol` | `openid-connect`
|
||||
`Access Type` | `confidential`
|
||||
`Valid Redirect URI` | `https://yourRancherHostURL/verify-auth`
|
||||
`Name` | `Groups Mapper`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `groups`
|
||||
`Add to ID token` | `OFF`
|
||||
`Add to access token` | `OFF`
|
||||
`Add to user info` | `ON`
|
||||
|
||||
- In the new OIDC client, create mappers to expose the users fields.
|
||||
- Create a new Groups Mapper with the settings below:
|
||||
1. Create a new `Client Audience` with the settings below:
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Groups Mapper`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `groups`
|
||||
`Add to ID token` | `OFF`
|
||||
`Add to access token` | `OFF`
|
||||
`Add to user info` | `ON`
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Client Audience`
|
||||
`Mapper Type` | `Audience`
|
||||
`Included Client Audience` | `CLIENT_NAME`
|
||||
`Add to access token` | `ON`
|
||||
|
||||
- Create a new Client Audience with the settings below:
|
||||
1. Create a new `Groups Path` with the settings below.
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Client Audience`
|
||||
`Mapper Type` | `Audience`
|
||||
`Included Client Audience` | <CLIENT_NAME>
|
||||
`Add to access token` | `ON`
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Group Path`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `full_group_path`
|
||||
`Full group path` | `ON`
|
||||
`Add to user info` | `ON`
|
||||
|
||||
- Create a new "Groups Path" with the settings below.
|
||||
:::warning
|
||||
|
||||
Setting | Value
|
||||
------------|------------
|
||||
`Name` | `Group Path`
|
||||
`Mapper Type` | `Group Membership`
|
||||
`Token Claim Name` | `full_group_path`
|
||||
`Full group path` | `ON`
|
||||
`Add to user info` | `ON`
|
||||
Rancher uses the value received in the "sub" claim to form the PrincipalID which is the unique identifier in Rancher. It is important to make this a value that is unique and immutable.
|
||||
|
||||
- Important: Rancher will use the value received in the "sub" claim to form the PrincipalID which is the unique identifier in Rancher. It is important to make this a value that will be unique and immutable.
|
||||
:::
|
||||
|
||||
## Configuring Generic OIDC in Rancher
|
||||
|
||||
@@ -80,7 +89,31 @@ Consult the documentation for your specific IdP to complete the listed prerequis
|
||||
|
||||
**Result:** Rancher is configured to work with your provider using the OIDC protocol. Your users can now sign into Rancher using their IdP logins.
|
||||
|
||||
## Configuration Reference
|
||||
### Custom Claim Mapping
|
||||
|
||||
Custom claim mapping within the Generic OIDC configuration is supported for `name`, `email` and `groups` claims. This allows you to manually map these OIDC claims when your IdP doesn't use standard names in tokens.
|
||||
|
||||
#### How a Custom Groups Claim Works
|
||||
|
||||
A custom groups claim influences how user groups work:
|
||||
|
||||
- If both the standard OIDC `groups` claim and the custom groups claim are present in the user's token, the custom claim supplements the list of groups provided by the standard claim.
|
||||
- If there is no standard groups claim in the token, the groups listed in the custom claim will form the user's only groups.
|
||||
|
||||
:::note
|
||||
There is no search functionality available for groups sourced from a custom claim. To assign a role to one of these groups, you must manually enter the group's exact name into the RBAC field.
|
||||
:::
|
||||
|
||||
#### Configuring Custom Claims
|
||||
|
||||
When on the **Configure an OIDC account** form:
|
||||
|
||||
1. Select **Add custom claims**.
|
||||
1. Add your custom `name`, `email` or `groups` claims to the appropriate **Custom Claims** field.
|
||||
|
||||
For example, if your IdP sends `groups` in a claim called `custom_roles`, enter `custom_roles` into the **Custom Groups Claim** field. Rancher then supplements the standard OIDC `groups` claim or looks for that specific claim when processing the user's token.
|
||||
|
||||
### Configuration Reference
|
||||
|
||||
| Field | Description |
|
||||
| ------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
@@ -91,6 +124,15 @@ Consult the documentation for your specific IdP to complete the listed prerequis
|
||||
| Rancher URL | The URL for your Rancher Server. |
|
||||
| Issuer | The URL of your IdP. If your provider has discovery enabled, Rancher uses the Issuer URL to fetch all of the required URLs. |
|
||||
| Auth Endpoint | The URL where users are redirected to authenticate. |
|
||||
|
||||
#### Custom Claims
|
||||
|
||||
| Custom Claim Field | Default OIDC Claim | Custom Claim Description |
|
||||
| ------------- | ------------------ | ------------------------ |
|
||||
| Custom Name Claim | `name` | The name of the claim in the OIDC token that contains the user's full name or display name. |
|
||||
| Custom Email Claim | `email` | The name of the claim in the OIDC token that contains the user's email address. |
|
||||
| Custom Groups Claim | `groups` | The name of the claim in the OIDC token that contains the user's group memberships (used for RBAC). |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you are experiencing issues while testing the connection to the OIDC server, first double-check the configuration options of your OIDC client. You can also inspect the Rancher logs to help pinpoint what's causing issues. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation.
|
||||
@@ -108,3 +150,7 @@ If the `Issuer` and `Auth Endpoint` are generated incorrectly, open the **Config
|
||||
### Error: "Invalid grant_type"
|
||||
|
||||
In some cases, the "Invalid grant_type" error message may be misleading and is actually caused by setting the `Valid Redirect URI` incorrectly.
|
||||
|
||||
## Configuring OIDC Single Logout (SLO)
|
||||
|
||||
<ConfigureSLOOidc />
|
||||
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Configure GitHub App
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github-app"/>
|
||||
</head>
|
||||
|
||||
In environments using GitHub, you can configure the new GitHub App authentication provider in Rancher, which allows users to authenticate against a GitHub Organization account using a dedicated [GitHub App](https://docs.github.com/en/apps/overview). This new provider runs alongside the existing standard GitHub authentication provider, offering increased security and better management of permissions based on GitHub Organization teams.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
:::warning
|
||||
|
||||
The GitHub App authentication provider only works with [GitHub Organization accounts](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts). It does not function with individual [GitHub User accounts](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#user-accounts).
|
||||
|
||||
:::
|
||||
|
||||
Before configuring the provider in Rancher, you must first create a GitHub App for your organization, generate a client secret for your GitHub App and generate a private key for your GitHub App. Refer to [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) for details.
|
||||
|
||||
### Create GitHub App
|
||||
|
||||
1. Open your [GitHub organization settings](https://github.com/settings/organizations).
|
||||
1. To the right of the organization, select **Settings**.
|
||||
1. In the left sidebar, click **Developer settings** > **GitHub Apps**.
|
||||
1. Click **New Github App**.
|
||||
1. Fill in the GitHub App configuration form with these values:
|
||||
|
||||
- **GitHub App name**: Anything you like, e.g. `My Rancher`.
|
||||
- **Application description**: Optional, can be left blank.
|
||||
- **Homepage URL**: `https://localhost:8443`.
|
||||
- **Callback URL**: `https://localhost:8443/verify-auth`.
|
||||
|
||||
1. Select **Create Github App**.
|
||||
|
||||
### Generate a Client Secret
|
||||
|
||||
Generate a [client secret](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication) on the settings page for your app.
|
||||
|
||||
1. Go to your GitHub App.
|
||||
1. Next to **Client Secrets**, select **Generate a new client secret**.
|
||||
|
||||
### Generate a Private Key
|
||||
|
||||
Generate a [private key](https://docs.github.com/en/enterprise-server/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys) on the settings page for your app.
|
||||
|
||||
1. Go to your GitHub App.
|
||||
1. Next to **Private Keys**, click **Generate a private key**.
|
||||
|
||||
## GitHub App Auth Provider Configuration
|
||||
|
||||
To set up the GitHub App Auth Provider in Rancher, follow these steps:
|
||||
|
||||
1. Navigate to the **Users & Authentication** section in the Rancher UI.
|
||||
1. Select **Auth Providers**.
|
||||
1. Select the **GitHub App** tile.
|
||||
1. Gather and enter the details of your GitHub App into the configuration form fields.
|
||||
|
||||
| Field Name | Description |
|
||||
| ---------- | ----------- |
|
||||
| **Client ID** (Required) | The client ID of your GitHub App. |
|
||||
| **Client Secret** (Required) | The client secret of your GitHub App. |
|
||||
| **GitHub App ID** (Required) | The numeric ID associated with your GitHub App. |
|
||||
| **Installation ID** (Optional) | If you want to restrict authentication to a single installation of the App, provide its specific numeric Installation ID. |
|
||||
| **Private Key** (Required) | The contents of the Private Key file (in PEM format) generated by GitHub for your App. |
|
||||
|
||||
:::note
|
||||
|
||||
A GitHub App can be installed across multiple Organizations, and each installation has a unique Installation ID. If you want to restrict authentication to a single App installation and GitHub Organization, provide the Installation ID during configuration. If you do not provide an Installation ID, the user's permissions are aggregated across all installations.
|
||||
|
||||
:::
|
||||
|
||||
1. Select **Enable**. Rancher attempts to validate the credentials and, upon success, activates the GitHub App provider.
|
||||
|
||||
After it is enabled, users logging in via the GitHub App provider are automatically identified and you can leverage your GitHub Organization's teams and users to configure Role-Based Access Control (RBAC) and to assign permissions to projects and clusters.
|
||||
|
||||
:::note
|
||||
|
||||
Ensure that the users and teams you intend to use for authorization exist within the GitHub organization managed by the App.
|
||||
|
||||
:::
|
||||
|
||||
- **Users**: Individual GitHub users who are members of the GitHub Organization where the App is installed can log in.
|
||||
- **Groups**: GitHub Organization teams are mapped to Rancher Groups, allowing you to assign entire teams permissions within Rancher projects and clusters.
|
||||
+4
@@ -203,3 +203,7 @@ To resolve this, you can either:
|
||||
3. Save your changes.
|
||||
|
||||
2. Reconfigure your Keycloak OIDC setup using a user that is assigned to at least one group in Keycloak.
|
||||
|
||||
## Configuring OIDC Single Logout (SLO)
|
||||
|
||||
<ConfigureSLOOidc />
|
||||
+12
@@ -120,6 +120,18 @@ For a breakdown of the port requirements for etcd nodes, controlplane nodes, and
|
||||
|
||||
Details on which ports are used in each situation are found under [Downstream Cluster Port Requirements](../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#downstream-kubernetes-cluster-nodes).
|
||||
|
||||
### IPv6 Address Requirements
|
||||
|
||||
Rancher supports clusters configured with IPv4-only, IPv6-only, or dual-stack networking.
|
||||
|
||||
You must provision each node with at least one valid IPv4 address, one IPv6 address, or both, according to the cluster networking configuration.
|
||||
|
||||
For IPv6-only environments, ensure you correctly configure the operating system and that the `/etc/hosts` file includes a valid localhost entry, for example:
|
||||
|
||||
```
|
||||
::1 localhost
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
You should never register a node with the same hostname or IP address as an existing node. Doing so causes RKE to prevent the node from joining, and provisioning to hang. This can occur for both node driver and custom clusters. If a node must reuse a hostname or IP of an existing node, you must set the `hostname_override` [RKE option](https://rke.docs.rancher.com/config-options/nodes#overriding-the-hostname) before registering the node, so that it can join correctly.
|
||||
|
||||
+1
-1
@@ -299,7 +299,7 @@ rancher_kubernetes_engine_config:
|
||||
useInstanceMetadataHostname: true
|
||||
```
|
||||
|
||||
You must not enable `useInstanceMetadataHostname` when setting custom values for `hostname-override` for custom clusters. When you create a [custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md), add [`--node-name`](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) to the `docker run` node registration command to set `hostname-override` — for example, `"$(hostname -f)"`. This can be done manually or by using **Show Advanced Options** in the Rancher UI to add **Node Name**.
|
||||
You must not enable `useInstanceMetadataHostname` when setting custom values for `hostname-override` for custom clusters. When you create a [custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md), add `--node-name` to the `docker run` node registration command to set `hostname-override` — for example, `"$(hostname -f)"`. This can be done manually or by using **Show Advanced Options** in the Rancher UI to add **Node Name**.
|
||||
|
||||
2. Select the cloud provider.
|
||||
|
||||
|
||||
+31
-32
@@ -103,11 +103,11 @@ The `worker` nodes, which is where your workloads will be deployed on, will typi
|
||||
|
||||
We recommend the minimum three-node architecture listed in the table below, but you can always add more Linux and Windows workers to scale up your cluster for redundancy:
|
||||
|
||||
| Node | Operating System | Kubernetes Cluster Role(s) | Purpose |
|
||||
| ------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| Node 1 | Linux (Ubuntu Server 18.04 recommended) | Control plane, etcd, worker | Manage the Kubernetes cluster |
|
||||
| Node 2 | Linux (Ubuntu Server 18.04 recommended) | Worker | Support the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster |
|
||||
| Node 3 | Windows (Windows Server core version 1809 or above) | Worker | Run your Windows containers |
|
||||
| Node | Operating System | Kubernetes Cluster Role(s) | Purpose |
|
||||
|--------|----------------------------------------------------------------------------------------|-----------------------------|-------------------------------------------------------------------------------------|
|
||||
| Node 1 | Linux (Ubuntu Server 18.04 recommended) | Control plane, etcd, worker | Manage the Kubernetes cluster |
|
||||
| Node 2 | Linux (Ubuntu Server 18.04 recommended) | Worker | Support the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster |
|
||||
| Node 3 | Windows (Windows Server core version 1809 or above required, version 2022 recommended) | Worker | Run your Windows containers |
|
||||
|
||||
### Container Requirements
|
||||
|
||||
@@ -126,8 +126,6 @@ If you are using the GCE (Google Compute Engine) cloud provider, you must do the
|
||||
|
||||
This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the [recommended architecture.](#recommended-architecture)
|
||||
|
||||
When you provision a cluster with Rancher on existing nodes, you add nodes to the cluster by installing the [Rancher agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) on each one. To create or edit your cluster from the Rancher UI, run the **Registration Command** on each server to add it to your cluster.
|
||||
|
||||
To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below.
|
||||
|
||||
### 1. Provision Hosts
|
||||
@@ -142,15 +140,15 @@ Your hosts can be:
|
||||
|
||||
You will provision three nodes:
|
||||
|
||||
- One Linux node, which manages the Kubernetes control plane and stores your `etcd`
|
||||
- One Linux node, which manages the Kubernetes control plane, stores your `etcd`, and optionally be a worker node
|
||||
- A second Linux node, which will be another worker node
|
||||
- The Windows node, which will run your Windows containers as a worker node
|
||||
|
||||
| Node | Operating System |
|
||||
| ------ | ------------------------------------------------------------ |
|
||||
| Node 1 | Linux (Ubuntu Server 18.04 recommended) |
|
||||
| Node 2 | Linux (Ubuntu Server 18.04 recommended) |
|
||||
| Node 3 | Windows (Windows Server core version 1809 or above required) |
|
||||
| Node | Operating System |
|
||||
|--------|----------------------------------------------------------------------------------------|
|
||||
| Node 1 | Linux (Ubuntu Server 18.04 recommended) |
|
||||
| Node 2 | Linux (Ubuntu Server 18.04 recommended) |
|
||||
| Node 3 | Windows (Windows Server core version 1809 or above required, version 2022 recommended) |
|
||||
|
||||
If your nodes are hosted by a **Cloud Provider** and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see [Selecting Cloud Providers.](../set-up-cloud-providers/set-up-cloud-providers.md)
|
||||
|
||||
@@ -164,11 +162,11 @@ The instructions for creating a Windows cluster on existing nodes are very simil
|
||||
1. Enter a name for your cluster in the **Cluster Name** field.
|
||||
1. In the **Kubernetes Version** dropdown menu, select a supported Kubernetes version.
|
||||
1. In the **Container Network** field, select either **Calico** or **Flannel**.
|
||||
1. Click **Next**.
|
||||
1. Click **Create**.
|
||||
|
||||
### 3. Add Nodes to the Cluster
|
||||
|
||||
This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node.
|
||||
This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the rancher system agent and allow Rancher to manage each node.
|
||||
|
||||
#### Add Linux Master Node
|
||||
|
||||
@@ -177,23 +175,18 @@ In this section, we fill out a form on the Rancher UI to get a custom command to
|
||||
The first node in your cluster should be a Linux host that has both the **Control Plane** and **etcd** roles. At a minimum, both of these roles must be enabled for this node, and this node must be added to your cluster before you can add Windows hosts.
|
||||
|
||||
1. After cluster creation, navigate to the **Registration** tab.
|
||||
1. In **Step 1** under the **Node Role** section, select at least **etcd** and **Control Plane**. We recommend selecting all three.
|
||||
1. Optional: If you click **Show advanced options,** you can customize the settings for the [Rancher agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) and [node labels.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
|
||||
1. In **Step 1** under the **Node Role** section, select all three roles. Although you can choose only the **etcd** and **Control Plane** roles, we recommend selecting all three.
|
||||
1. Optional: If you click **Show Advanced**, you can configure additional settings such as specifying the IP address(es), overriding the node hostname, or adding [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
|
||||
1. In **Step 2**, under the **Registration** section, copy the command displayed on the screen to your clipboard.
|
||||
1. SSH into your Linux host and run the command that you copied to your clipboard.
|
||||
|
||||
**Result:**
|
||||
**Results:**
|
||||
|
||||
Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster.
|
||||
Your cluster is created and assigned a state of **Updating**. Rancher is standing up your cluster.
|
||||
|
||||
You can access your cluster after its state is updated to **Active**.
|
||||
It may take a few minutes for the node to register and appear under the **Machines** tab.
|
||||
|
||||
**Active** clusters are assigned two Projects:
|
||||
|
||||
- `Default`, containing the `default` namespace
|
||||
- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces
|
||||
|
||||
It may take a few minutes for the node to be registered in your cluster.
|
||||
You’ll be able to access the cluster once its state changes to **Active**.
|
||||
|
||||
#### Add Linux Worker Node
|
||||
|
||||
@@ -203,11 +196,13 @@ After the initial provisioning of your cluster, your cluster only has a single L
|
||||
|
||||
1. After cluster creation, navigate to the **Registration** tab.
|
||||
1. In **Step 1** under the **Node Role** section, select **Worker**.
|
||||
1. Optional: If you click **Show advanced options,** you can customize the settings for the [Rancher agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) and [node labels.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
|
||||
1. Optional: If you click **Show Advanced**, you can configure additional settings such as specifying the IP address(es), overriding the node hostname, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
|
||||
1. In **Step 2**, under the **Registration** section, copy the command displayed on the screen to your clipboard.
|
||||
1. SSH into your Linux host and run the command that you copied to your clipboard.
|
||||
|
||||
**Result:** The **Worker** role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.
|
||||
**Results:**
|
||||
|
||||
The **Worker** role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.
|
||||
|
||||
:::note
|
||||
|
||||
@@ -216,7 +211,7 @@ Taints on Linux Worker Nodes
|
||||
For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.
|
||||
|
||||
| Taint Key | Taint Value | Taint Effect |
|
||||
| -------------- | ----------- | ------------ |
|
||||
|----------------|-------------|--------------|
|
||||
| `cattle.io/os` | `linux` | `NoSchedule` |
|
||||
|
||||
:::
|
||||
@@ -231,12 +226,16 @@ The registration command to add the Windows workers only appears after the clust
|
||||
|
||||
1. After cluster creation, navigate to the **Registration** tab.
|
||||
1. In **Step 1** under the **Node Role** section, select **Worker**.
|
||||
1. Optional: If you click **Show advanced options,** you can customize the settings for the [Rancher agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) and [node labels.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
|
||||
1. Optional: If you click **Show Advanced**, you can configure additional settings such as specifying the IP address(es), overriding the node hostname, or adding [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
|
||||
1. In **Step 2**, under the **Registration** section, copy the command for Windows workers displayed on the screen to your clipboard.
|
||||
1. Log in to your Windows host using your preferred tool, such as [Microsoft Remote Desktop](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients). Run the command copied to your clipboard in the **Command Prompt (CMD)**.
|
||||
1. Log in to your Windows host using your preferred tool, such as [Microsoft Remote Desktop](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients). Run the command copied to your clipboard in the **PowerShell Console** as an Administrator.
|
||||
1. Optional: Repeat these instructions if you want to add more Windows nodes to your cluster.
|
||||
|
||||
**Result:** The **Worker** role is installed on your Windows host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster. You now have a Windows Kubernetes cluster.
|
||||
**Results:**
|
||||
|
||||
The **Worker** role is installed on your Windows host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.
|
||||
|
||||
You now have a Windows Kubernetes cluster.
|
||||
|
||||
### Optional Next Steps
|
||||
|
||||
|
||||
+2
-1
@@ -20,7 +20,8 @@ Then you will create an EC2 cluster in Rancher, and when configuring the new clu
|
||||
- [Example IAM Policy](#example-iam-policy)
|
||||
- [Example IAM Policy with PassRole](#example-iam-policy-with-passrole) (needed if you want to use [Kubernetes Cloud Provider](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md) or want to pass an IAM Profile to an instance)
|
||||
- [Example IAM Policy to allow encrypted EBS volumes](#example-iam-policy-to-allow-encrypted-ebs-volumes)
|
||||
- **IAM Policy added as Permission** to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user.
|
||||
- **IAM Policy added as Permission** to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to a user.
|
||||
- **IPv4-only or IPv6-only or dual-stack subnet and/or VPC** where nodes can be provisioned and assigned IPv4 and/or IPv6 addresses. See [Amazon Documentation: IPv6 support for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html).
|
||||
|
||||
## Creating an EC2 Cluster
|
||||
|
||||
|
||||
Reference in New Issue
Block a user